Model-based generation of project documentation [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

Improve this question

During the development of my projects I find myself producing some large documents with slight variations on only a few paragraphs. For instance, the same configuration plan will be used throughout different projects but each document has to be tailored with specific data and to comply with some specific requirements. Being a lazy person and a fan of model-driven development, I have been looking for ways to optimize this process and I got these options:

• Document templates - Using master document templates (the presentation) with forms (the model) or restricting the edition of a document to only a few key fields, and then cross-referencing the inputted data all over the document would do the trick... but I still feel that I could de-couple both layers a bit more.
• UML modeling - Using CASE tools with UML support, I thought I could model my documents as packages and classes with annotations, change the model for each project and generate a report using a document template. The problem is that those tools are not designed for treating large chunks of text and I am having some difficulties to progress.
• Process modeling - Using Eclipse EPF https://www.eclipse.org/epf/ seems a bit overkilling for what I want to accomplish. Remember: I´m a lazy person.

I would like to ask the community on their experiences with model-based documentation or their ways to optimize the generation of documents throughout the software development cycle.

Answer 1

I'm not sure I fully understand, so apologies if this misses the mark.

I've faced (I think) a similar problem, where there's a many:many relationship between content and the documents it needs to be presented in. For example, a 'project overview' that needs to be included in a requirements document, project plan, etc.

Thus far the best solution I've found is:

1. Write each section in Markdown format. There are some nice editors that make writing Markdown easy and efficient (e.g. Mou on OSX).
2. Use Pandoc to convert Markdown into Restructured Text (RST).
3. Use Sphinx to generate documents from the RST files.

I have multiple Sphinx doc templates, each of which combines some of the common sections with others specific to that doc. If one of the common sections gets updated it's easy to re-generate all docs to incorporate. Version Control is pretty straightforward as the source files are all simple text. Sphinx can also generate multiple formats easily: for example html to put online, or pdf for printing/distribution.

You could remove the need for step 2 by writing in RST natively. For me the extra step is worth it as I haven't found an RST editor that's as comfortable or efficient as Mou. YMMV of course.

It's not a perfect solution: for example, creating links across sections isn't that easy. But in general it works well for my needs.

hth.