I’ve reached that stage where I have to look back on my model to determine how this section of the app works and that’s time consuming. It gets worst when I made a small change.
At Talis, @chrisc showed us a brief overview of a documentation of their website but it never called to mind to ask what was used to create it. What I want is a website or just the best tool to use to create a documentation for my app. Something I can edit easily and fits for its purpose. What do you use?
What sort of documentation? What is your target audience?
If it’s other devs, including yourself in 2 years time, have a look at Sparx Enterprise Architect. I don’t have it any more and I really miss it. It’s amazing value unless you are used to everything being free 
I think I used the Professional edition.
I mainly use class and activity diagrams, so I’m trying to use Umbrello on Linux as a free substitute. I got it working on my Pi 2 yesterday. It’s less accurate on Pi than Ubuntu but it’s adequate for simple diagrams. It’s a teeny bit buggy so save often.
It wasn’t Swagger by any chance?
I last worked in an agile .Net environment, the devs believed that the code should document itself, or auto-generate docs from the comments and database. That leaves you needing big pictures that show how all the lumps fit together, and a record of whats/whys ofdesign decisions. Detailed documentation can become a maintenance overhead. Photos of whiteboards are an agile favourite but I like UML because it prevents you needing to keep drawing versions of the same diagram. A good tool works with a single model that keeps all your changes consistent throughout all diagrams.
I thought about mentioning MarkDown. I’m still not sure it’s up to the job but I haven’t learned to use DITA or DocBook properly. I use a free tool called ReText to write it. You can publish MarkDown as books at LeanPub, straight from Dropbox or Github.
I mean what do you use to write your documentation for you app. Instead of using MS Word or some other, whats best to use that can easily edit and in a safe place?
I believe in ‘separation of concerns’, so I’d like the structure, content and styling to be dealt with individually but I’ve struggled to find easy-to-use free tools to write DocBook XML or DITA. These treat marked-up text as input to a tool-chain to produce output in a number of formats or with different styling, like you’d compile source code for different targets.Text is just a language, like JavaScript
I put off the problem to another day by writing chunks of text in MarkDown in ReText with it’s live preview switched on, and save on Dropbox. I occasionally back up my Dropbox to a local drive too.
I think I should move to a Git repository so I have at least 2 copies & change-tracking. I’ve never believed in controlling change, just knowing what I did.
Trying to write a bigger body of text with unknown structure, I have other problems but I don’t think they should worry you.
I see what you are saying. So, what are the paid service for this? If anything, I’ll stick with Apple’s Pages and edit in icloud.com
I’m not paying for any of that. Text files aren’t very big so I use the free DropBox allowance. If I LeanPub a book, they’ll take about10% but if you give stuff away it doesn’t cost anything
I tend to write most docs in markdown these days. There’s a free app call mou that does a decent the job. I write a lot, so I tend to use Ulysses, which comes with a price tag. It syncs to iCloud or you can edit locally. I like that there’s an iPad version too, so docs follow you regardless of device. It can output text, html, epub, pdf, and docx.
For web-based docs, I use jekyll and edit md file in Ulysses.
(For balance, I also love scrivener for long form writing, but it’s not the right tool for most tech docs. ymmv.)
By the looks of it, it sure does. I’ll go with that as I want to add few code snippets as I write the documentation. I tend to forget at times.
That’s how I use ReText , Umbrello and Freemind. You get the performance of a local app and DropBox does the synch between my devices of the text file data.
@auxbus I want to do my long-form writing by building out of components
I used to use Freemnid (for years on Linux), but it became troublesome on OSX, so I moved away. I don’t know ReText and Umbrello.
Dropbox is problematic for those of us involved with security. Perhaps I’ll be proven wrong to trust Apple, but I do for now.
Isn’t that what Microsoft tried to do with OLE 20 years ago? I can mostly do it with scrivener, though it’s not how I choose to write. It would be nice to have a unified interface between docs. Even per platform.
I’d have to agree with the people suggesting Markdown here. It doesn’t matter what you write it in. I use VSCode with a Markdown Preview addon.
Write everything in Markdown and then you can convert it to whatever you want. There are command line tools for generating Word docs from markdown. You can stick it on a github wiki. You can use github pages or jekyll to generate a static site from it.
It’s just the most flexible option. As for where you store it… where do developers store anything? In a repo.
The documentation would be private. Github pages support private pages? I have not checked.
No github pages has to be public I think. But you could still just check markdown into a private repo and integrate it with Jekyll to publish it to a static site privately.
I can’t really say how difficult this is at the moment. It’s something I’m still working on. I have the same situation where I want documentation to be private, at least initially.
You can have a github wiki on a private repo. This is is what I have at the moment and it works, it’s just not quite as nice that you can’t modify the theme and navigation etc.
I beg to differ. Sure, I use sublime + plug-in for a lot of dev docs, but at a point, better tools provide a better experience and provide more features.
(Aside: I dislike unqualified assertions. There’s far too much of it in software development. And yeah, I probably do it myself from time to time, but I work not to. Javascript is still crap, though )
Yeah of course. I guess I meant choose the tools you prefer to write it with. It just doesn’t bother me that much because I don’t tend to write anything overly complicated with markdown.
MarkDown is for people who want seperation of concerns but don’t care much about structure or presetation
You can pay for Github privacy or get it free at Bitbucket. It’s still git.
Any love for rubiest?
Proudly sponsored by Bytemark