It is necessary to choose the appropriate language for writing documentation in
Currently the documentation I'm working on is a bit in a state of the art. There isn't enough somewhere, and the documentation that does exist extends to many Word documents, making it difficult to find anything.
I'm trying to take the lead and improve it, and I believe the first thing to do is find the best format for writing documentation in:
- My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html help style) and structured in a suitable tree:
- It would be nice to create a standalone Html-Help style package that will come with the application
- Apart from being able to create a website in MSDN format as a reference for those too lazy to look at the CD.
- Search is of course required
- It should be at least simple enough to update - if there is a 17-step process for updating published documentation, then it makes too much work to do simple changes and no one can be bothered about updating it.
- The documentation is technical in nature and so it would be ideal to be able to include generated documentation from things like Xml documentation embedded in C # code. This is, however, definitely a side requirement - very little useful Xml documentation exists at this time, it's just that I plan to fix it in the future.
- For the same reason, it is often useful to handle things like attachments (code examples, etc.). I'm not expecting anything out of the ordinary, but this is what I need to keep in mind to make sure its at least not being handled badly.
Are there any projects or languages suitable for this kind of documentation?
source to share
I started using DokuWiki . It's not exactly what I was originally looking for (I think I was actually looking for a CMS), but it does the job and some respect for her better than I originally had in mind (in particular her wiki - I haven't gotten to it yet) that posted this to our clients, but so I'm not sure how well it will turn out)
I use the IndexMenu plugin and Arctic to get the navigation tree on the left, and if I publish a wiki, I use the discussion plugin so users can submit feedback.
My current method of handling the generated content is to use xslt templates to create dokuwiki syntax and write that output directly to files / folders in the data / pages folder.
source to share
I've had good results with doxygen on my C and C ++ projects, although it supports many other languages as well. You put documentation in comments in your code, which can be simple or complex HTML markup. It is very easy to update it as it is part of the code. You can make the assembly of documents part of the assembly process. Additional non-API topic can be added as separate HTML documents. The version I am using does not support search, so you will have to add another search product on these pages. Since this is HTML, you can add code samples, diagrams, etc.
source to share
If you are using LaTeX , you can get all your documentation in great PDFs and hard copies, and the ability to generate html (via latex2html ). The advantage of TeX is that it is also clear text, so you can track / reliably link it to your favorite source control system.
source to share
We use confluence as our documentation repository. It is fairly easy to have public and private sections and has a good WYSIWYG editor. It can handle attachments and can be saved as PDF documents if you like.
source to share
The clean way is to use DocBook . It's easy to write and understand. It is also easy to parse because XML parsers are standard and other forms of documentation (such as from inline documentation in comments) can be easily converted to this format.
Directly create PDF, HTML and other formats from a DocBook source (tools exist for this purpose).
source to share