Dev.maidsafe.org

can we host a documentation / tutorial / examples with articles written on different levels of comfort into a nicely readable website as this forum is?

A wiki could be an option, but Chris A. suggested to aim for the comfort and ease of use of Git - Documentation

any web wizards?

1 Like

Great move. If we could find sites we all like then figure out the best mechanism to get this done I am sure we will get help. I like that git-scm is a gihub hosted site. That allows pull requests and frequent updates.

Boost is pretty good I think, but maybe biased as its a bit deep pretty fast. I agree though and think we may need sections like:
How it works
Why it works
Core development and building (maybe our wiki’s updated)
Using the API (example apps etc. as we are looking to create)

Bottom line is we are rubbish so far. It would be amazing to have somebody suck the info from our heads and format it in a nice manner. It needs to be fast acting I think. There are a ton of software doc sites out there. Many age very fast though and doxygen stuff is horrible.

2 Likes

I think I know the perfect tool: http://www.gitbook.io. I saw it on Hacker News a month ago. It looks really cool.

Looks very cool and maybe the very job. Only doubt is c++ c# etc. code snippets.

Satisfies the github hosting etc. We should try a test for this. I might ask @scottmmack in the office to give it a whirl to see how that does as far as edits and pull requests etc. Good find.

1 Like

GitBook uses highlight.js for syntax highlighting, which supports 71 languages (including C++ and C#). So that shouldn’t be a problem.

Also, I just found out that they provide a very nice editor which is available for Windows, Mac and Linux. Here’s a screenshot:

1 Like

@frabrunelle Nice find. Gitbook does look quite nice. Shona’s having a look at this and if it seems capable enough, we could even host our example’s documentation on it as a start and see how people find it to use.

Thanks for that :slight_smile:

2 Likes

So I did a fork of the gitbook maidsafe-examples repo and got the editor to run locally. I had a couple issues with where to run the npm commands from using the “Gitbook Update Instructions”. I added an issue on that repo explaining the error I was getting and why. I also had some issue with grunt publish but I think that is more just my lack of knowledge with using grunt. I’ll keep trying to figure that part out.

Is the above repo also where we want to add the (never mind - I see that the example site is being used as a proof of concept for the main docs):

Sorry, I’m feeling a little lost as to where I should apply my effort and I know you all are pretty busy :wink: so I’ll patently keep my eyes on the forum and do what I can…

Have replied to your issue on github itself. My guess is the problem was due to the package name containing spaces. Have made a commit which should hopefully address that. So if you update master branch and try again, it should be fine.

From a fork you wouldn’t want to run “grunt publish”. That command tries to update the live gitbook as in the examples project gitbook from it’s gh-pages branch. If you’re making content updates on a fork, please just submit a pull request to master branch on the source repo. If you want to test the changes you made locally, from the GitBook editor tool you have the option to “Preview Website” from it’s menu’s or you can just run “grunt” from the gitbook_src folder which should build the site locally that you can check with a browser. I’ve added a note to the Update Instructions wiki indicating the same.

Proposal to try to use the new wiki feature of discourse as the docs…

We certainly could for discussions and tutorials.

I still feel API docs should be out of such a style. As soon as I think of API docs, my mind goes to a layout such as

MSDN - Button Class

Qt - QPushButton

Xamarin - UIButton

Personally I’m not so much for Boost Docs but that could just be me :stuck_out_tongue:

I like your first 3 examples too. The Boost docs can be a hit or a miss, but they’re generally pretty comprehensive. If they stuck to a consistent style/format across all libs it would help, but since each lib has a different maintainer they’ve got a bit of leeway on that front. I think we can avoid such issues.

Do you know if the other 3 are all auto-generated from source files (i.e. comments in headers), or are they maintained by hand?

Think it’s hard to find exact details for their generation procedure. From online comments in various places my guess would be:

Qt: QDocs
MSDN: Sandcastle type doc engine
Xamarin: MonoDoc revision by the looks of it

MSDN seems to have locked down their doc generation tool - sandcastle since 2012. Since then a opensource project has the equivalent for Managed projects. Not much luck for native languages. Xamarin - did not look too hard tbh. Think their’s is the least of the three I prefer.

QDoc seems a nice tool from basic skimming through:

QDoc Commands seem quite extensive and seem to cover every requirement within Qt documentation itself. Also has the benefit of being cross-OS and already bundled with the super project for integration.

Might be a nice task to try and check the output on a new project.