Home/ Questions/Q 411553
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-12T17:59:53+00:00

Currently the documentation where I work is in a bit of a state. There

  • 0

Currently the documentation where I work is in a bit of a state. There isn’t anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.

I’m trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the 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 good to be able to produce a standalone Html-Help style package to be shipped with the application
    • As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
    • Search is of course a must-have
  • It needs to be at least reasonably easy to update – if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
  • The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement – currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
  • For the same reason it is often good to be able to handle things like attachments (code samples etc…) I’m not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.

Are there any projects or languages that are suited to this sort of documentation?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    I’ve started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki – I’ve not yet gotten as far as publishing this to our customers however so I’m not sure how well thats going to work out)

    I’m using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I’ll use the discussion plugin to allow users to post feedback.

    Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the “data/pages” folder.

    • 0