5 ms·

This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big in

by Kranar 6y ago

This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big inconsistencies. Setting up MediaWiki and throwing it up on a Linode server costs 20 bucks a month and can be deployed from a Docker image in roughly 15-20 minutes. It can referenced by everyone, anyone can contribute to it with a full audit of changes, and it's easily searchable. I use it to document technical and non-technical things like company policies, work flow processes, security practices, coding style, pretty much anything. New employees have a standardized on-boarding process that is clearly documented step by step for them to get setup with everything they need to start being productive by their second day of working here. It's actually fairly low effort to do this and is a lot easier than having a bunch of people have to remember God knows what and when, or forgetting and then having to ask someone else who may have a vague recollection of it. An authoritative source of knowledge that everyone has access to and anyone can contribute to is worth setting up.

tharkun__ 6y ago
Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md? Easily searchable on my machine with grep or ack or whatever you use. Many tools (such as github, many IDEs etc.) open it up with when you open up the project, including formatting it. If you really want, you can serve it up somewhere via HTTP. When something changes I can commit it right with the changes I'm making.
- Kranar 6y ago
  I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
  - tharkun__ 6y ago
    You should not assume and I should have specified more clearly. Our code style is also committed. As spotless configuration files, eslint configuration files etc. You can run these locally if you want to. Our CI/CD definitely runs them and fails the build if it doesn't pass. No exceptions. The README.md I am speaking of is actually more than one README.md. We have more generalized ones dealing with "This is how to set up your dev env, so you can actually develop stuff", to more module specific ones like "this module is special from everything else in X, Y and Z".
- GSGBen 6y ago
  This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
  - tharkun__ 6y ago
    I completely agree with you for documentation that is not developer centric. A wiki and a WYSIWYG editor is the way to go there. Though it is funny to see PMs and other people fight with say the Confluence editor (that's what I'm stuck with at the moment @work and they've recently effed up the Jira editors as well in favour of non-developers). It's abysmal and since they changed it to remove proper wiki syntax editing I can't even really fix things for them easily and have to use workarounds myself instead of teaching them a little bit of wiki markup syntax from time to time or using it myself to fix things. It's like MS Word and everyone learning all the workarounds of how to undo weird formatting or fix documents. What was wrong with LaTeX? :) That is absolutely not what we're talking about here though. If a project manager really wants to set up a local dev env for whatever reason, they can be my guest but don't expect me to tailor our whole everything around them and not my developers.
taneq 6y ago
I do the same, even just for my own notes. That way it's all there, accessible, searchable, in the same place. Far better than everyone squirreling their own critical data away in a different tree-trunk.
steve_g 6y ago
I got really excited about the Linode/mediawiki solution. We're looking at Jira/Confluence right now, and it seems pretty heavyweight. But then I remembered nothing takes 20 minutes. I'll bet it takes 20 minutes to set up the wikimedia server and then 4 days of Googling to get our single sign-on to work. We'll have to figure out what to do with backups. Plus we'll need to document the documentation process itself and do the painful change management with the organization. Finally, we don't use Linux, so it would probably take more than 20 minutes to figure this stuff out. It's a great idea, but it's a non-trivial amount of work. Not that I disagree with your approach, but I'm saddened when I think about how to get there.

by Kranar 6y ago

tharkun__ 6y ago

Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md? Easily searchable on my machine with grep or ack or whatever you use. Many tools (such as github, many IDEs etc.) open it up with when you open up the project, including formatting it. If you really want, you can serve it up somewhere via HTTP. When something changes I can commit it right with the changes I'm making.

Kranar 6y ago
I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
- tharkun__ 6y ago
  You should not assume and I should have specified more clearly. Our code style is also committed. As spotless configuration files, eslint configuration files etc. You can run these locally if you want to. Our CI/CD definitely runs them and fails the build if it doesn't pass. No exceptions. The README.md I am speaking of is actually more than one README.md. We have more generalized ones dealing with "This is how to set up your dev env, so you can actually develop stuff", to more module specific ones like "this module is special from everything else in X, Y and Z".
GSGBen 6y ago
This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
- tharkun__ 6y ago
  I completely agree with you for documentation that is not developer centric. A wiki and a WYSIWYG editor is the way to go there. Though it is funny to see PMs and other people fight with say the Confluence editor (that's what I'm stuck with at the moment @work and they've recently effed up the Jira editors as well in favour of non-developers). It's abysmal and since they changed it to remove proper wiki syntax editing I can't even really fix things for them easily and have to use workarounds myself instead of teaching them a little bit of wiki markup syntax from time to time or using it myself to fix things. It's like MS Word and everyone learning all the workarounds of how to undo weird formatting or fix documents. What was wrong with LaTeX? :) That is absolutely not what we're talking about here though. If a project manager really wants to set up a local dev env for whatever reason, they can be my guest but don't expect me to tailor our whole everything around them and not my developers.

taneq 6y ago

I do the same, even just for my own notes. That way it's all there, accessible, searchable, in the same place. Far better than everyone squirreling their own critical data away in a different tree-trunk.

steve_g 6y ago

I got really excited about the Linode/mediawiki solution. We're looking at Jira/Confluence right now, and it seems pretty heavyweight. But then I remembered nothing takes 20 minutes. I'll bet it takes 20 minutes to set up the wikimedia server and then 4 days of Googling to get our single sign-on to work. We'll have to figure out what to do with backups. Plus we'll need to document the documentation process itself and do the painful change management with the organization. Finally, we don't use Linux, so it would probably take more than 20 minutes to figure this stuff out. It's a great idea, but it's a non-trivial amount of work. Not that I disagree with your approach, but I'm saddened when I think about how to get there.