Software Beyond Code

In my previous post , I made the case that developer documentation was useful and that it could be easily done with LaTeX, given some basic structure. Although LaTeX has the same advantages as any code because of its abstraction from the final document, it also has its downfalls. Probably the most repulsing to newcomers is the lack of feedback over what the document looks like in its final form. There exist a couple of tools such as TexMaker , but I found that taking the road to create my own editor-like environment has been more simple and has given me more control over what I wanted to do: write developer documentation. This short entry will try to show how easy it is to integrate LaTeX editing with feedback with remotely any editor using the structure already presented. The right things at the right place One thing TexMaker and the likes does well is to provide a preview of your document in a secondary panel. One thing it doesn't really do is... well everything not LaTeX. Wh...

Developer documentation in software projects In many projects and prototypes, documentation in text form is a simple way to easily understand some basics of a project and to start off development by explaining key design choices and concepts. There are many ways to provide such documentation, but often a README plain text file is provided. Such plain text might not effectively allow be the most straightforward communication mean; we all know that an image is worth a thousand words. Schemas, UML diagrams, formatted code snippets, color, and other more advanced mediums and media content cannot be easily added and is impossible to present in a concise way. Another way is to use formats such as Microsoft Word or LibreOffice documents. This is probably one of the most convenient way to include additional formatting and content, but strongly lack in the area of versioning where changes cannot be dealt with in a similar way to code. Developers used to version control in software projects ca...