5

We have written a custom software framework and it has grown to the point where we are ready for documentation. This documentation will be used by other developers to share knowledge. I am concerned with how to do the documentation for the features and descriptions.

My co-worker suggested a Word document with sections and a feature matrix. I am not too keen on that and would like to find an alternative. What have you used in the past, good and bad parts? I couldn't find anything in particular on documenting features, I guess looking at something like a bootstraps website is a good start but creating a website for this is not doable. Are there any charts that may aid in documenting the features?

Edit: Custom Software Framework for building Web Applications. The framework is built using C# + .Net...

  • Welcome to Writing.SE Grim, glad you found us. We have a tour and help center you might wish to check out. – Cyn says make Monica whole Sep 24 at 17:44
  • We ask that people wait at least 1-2 full days before accepting an answer as best. This gives other people a chance to answer, which is of course what you want, several strong answers. Do upvote every answer you like. There's no time limit for accepting an answer and you'll always get your two points. Thanks! – Cyn says make Monica whole Sep 24 at 21:48
  • What software are you trying to document? The language and nature of the tool will have an impact on what the best tool to use is. – linksassin Sep 26 at 5:12
  • Its a custom software framework for internal use. C# + .Net... – Grim Sep 26 at 15:21
6

I would definitely not recommend using Word for this. It is just not what it was designed to do.

There are multiple documentation systems that have been developed specifically for the purpose of writing developer documentation. They provide frameworks and tools, and, what may be more important to you at this stage of the project, examples of what works.

It is impossible to say which would be preferable for your particular project without knowing far more about it. But as a place to start I would suggest that you investigate Sphinx. Sphinx is the tool that was developed to document the python programming languages and the various libraries, modules, and platforms that are associated with it. It is widely used for similar projects.

A lighter weight, and therefore less capable but simpler alternative is Jekyll which is also used for documenting many software products. It is a more generic model, so it won't give your as much help and guidance, but it is very straightforward to use and you could draw on the examples of many other organizations.

  • 1
    I can't understand why you have not accepted the recommendations in this answer. Why not use Jekyll or Sphinx. – S. Mitchell Sep 24 at 19:46
  • @Grim, well both Sphinx and Jekyll are text based and Word is not, so there you go. – user16226 Sep 24 at 20:13
1

Personally I use Latex, more specifically pdflatex, which is free to download. It is text-based, learning it will probably take a week or two, but there are online examples and help through StackExchange.

The advantage is you can produce charts, diagrams, flowcharts and anything else you want (art for example) using other packages, in their own PDF files, and then "include" them in your documentation.

For myself, as a research scientist, some of my graphs can be complex and we use special packages to produce them, and not always the same packages. I might produce a few with just a spreadsheet, and some diagrams with Draw, and others with a specialty package designed to draw, say, molecular diagrams, or engineering diagrams.

Latex itself is the best way (by far IMO) to render complex mathematical equations, and to back-reference in the text or build a bibliography.

In technical fields (STEM) at least I think this is the package most used in academia and research, in the four universities I have attended or worked at, it is difficult to finish a PhD in a STEM field without being versed in Latex.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.