6 ms·

Alternatively: abandon wikis and keep documentation in your monorepo, next to the code/project it concerns (and in a doc/ global path for orga-wide documentatio

by q3k 6y ago

Alternatively: abandon wikis and keep documentation in your monorepo, next to the code/project it concerns (and in a doc/ global path for orga-wide documentation). Then render it with whatever - I wrote a little tool [1] for that, because I couldn't find anything that worked for this usecase. Lowering the effort barrier for documentation work (ie. making it easy, and expected for developers to commit documentation changes _alongside_ code changes) has been critical for the organizations I've worked with. Disorganized, slow-loading wikis with obtuse syntax markup tends to make people really not want to touch docs, or keep postponing cleanups. Developers will thank you for making the documentation grepable, for using standard code editing/review/submission flow for documentation changes, and for making ownership of documentation clear. [1] - https://hackdoc.hackerspace.pl/devtools/hackdoc/README.md?ref=master https://hackdoc.hackerspace.pl/devtools/hackdoc/README.md?re...

matanrubin 6y ago
In most companies I've worked for only part of the contibuters to the company's Wiki were developers. What about Product Managers, BizDev people, etc? Do you expect everyone at the company to use git and work with markdown? (Don't get me wrong, I wish everyone did. But knowing people in these roles makes me think this would never happen)
- londons_explore 6y ago
  The solution to this is to make a UI which can be used like a wiki, but in fact creates a git commit for each edit. Allow documentation-only changes without reviews or pull requests etc. Still use ACL's in the monorepo so that people can edit their own documentation with a single click, but to edit another teams docs requires some kind of pull request/approval from that team. Create a culture that code changes must have accompanying documentation changes, and that any substantial code change without documentation changes needs a good reason. Then everyone can use the tools they are familiar with, and still get all the benefits of history and always-uptodateness.
- tln 6y ago
  I may be in an unusual position of being able to dictate this but I always push for non-coders to use git and markdown... design assets are checked in to a repo, blog posts use markdown and are pushed to a Netlify site, marketers can tweak language and images directly in our Vue app (partly chosen for Vue's fantastic accessibility), etc. TBH I have not pushed non-coders to document stuff in git / markdown, only the developers do that. Free, friendly tools like Github desktop, VS code, Netlify CMS help a ton. It also helps that marketers, designers, product managers are all technically inclined positions, where hiring smart people pays off. There's a tradeoff as it takes more time to preach and teach the use of these tools, but I see it as a good investment for workflow and in people. Being able to wrangle git is a great skill!
  - scoopertrooper 6y ago
    This would be insanity in a mono repo. A developer would have to look over every PR to make sure some critter from the marketing department didn't accidentally change an important bit of code.
    - dustinchilson 6y ago
      1) You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage. 2) It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team. 3) This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.
      - scoopertrooper 6y ago
        > You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage. Hard to catch everything > It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team. I'm all for open access, but systems should have safety rails to stop people from making mistakes. This is why we have the PR process in the first place. If you have non-programmers approving PRs created by other non-programmers into repositories that have mission critical code, then you're really just asking for trouble. > This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell. My position actually straddles product and development, so I spend much more time with marketing types than developers these days. They're fine people, but they aren't as patient and detail oriented as developers and lack awareness of the dangers of certain actions. I've seen them do all sorts of crazy stuff that would throw the security team into an absolute fit if they found out about it.
- dehrmann 6y ago
  If you can learn pivot tables in Excel, you can learn markdown.
mancini0 6y ago
This looks great and I wish my company adopted the monorepo & bazel. The navigation to //devtools from the link you shared results in a 404 however - perhaps the tool's routing is confused by the bazel "//<project>" syntax? Maybe not as I see the url path looks correct, maybe parent directory links should not show as active if there is nothing to serve in the parent directory.
- q3k 6y ago
  It's broken :) This is mildly internal for now, and needs a bunch of bug fixes before release. The behaviour I would expect for this is that the 'devtools' part of the path shouldn't be clickable - as there isn't any documentation markdown in that path of the repository. I'll see if I can implement this today. EDIT: fixed.
tln 6y ago
I prefer this as well (except for the monorepo part :) ) for anything that concerns the code/app in any way. We chose Slab for our wiki partly because it can surface markdown files from github. So, the onboarding guide just links to relevant markdown files right in Slab.
malkia 6y ago
THIS ^^^ Google took this approach internally using markdown files (If I remember correctly). Perforce is also going this way - https://www.perforce.com/manuals/swarm/Content/Swarm/basics.markdown.html https://www.perforce.com/manuals/swarm/Content/Swarm/basics.... - but I wish more (right now it's only in their "project overview pages.") This allows for code reviews on the doc too, easier to auto-generate, fix, etc - than non-file interface like wiki.
- malkia 6y ago
  One gotcha - if your playbook is stored there, make sure it's backup'd on secure external USB drives, as the source system, or the markdown render, or something else needed to accomplish this may go down, and now you and your team/project are going to be affected. Like pre-rendered to .html, .chm, even why not pdf files - whatever it takes just to be able for your oncall personnel to read them back if need to.
  - tln 6y ago
    Presumably your on-call personnel will have those repos checked out?
    - malkia 6y ago
      What if your source system goes down, can't connect to your local machine, needs to use VM - no the oncall needs to have the USB stick or more, and use it any other company laptop.
      - q3k 6y ago
        Hackdoc itself has a mode to run from a local checkout, with no other service dependencies (vs. the production mode that expects a git/grpc proxy service to access the live repository), and as it's Go it can easily be moved around as a single, relocatable binary that will run from nearly all operating systems.
- q3k 6y ago
detaro 6y ago
I feel like there's a vast difference between documentation relevant to code and a lot of the stuff accumulating in a company wiki. And if you put the latter in a global path, it doesn't become magically better maintained just because your wiki is backed by a repo. Age without further context is in any case a terrible indicator of relevance. What's IMHO important is a culture of providing the context with your entries.

by q3k 6y ago

matanrubin 6y ago

In most companies I've worked for only part of the contibuters to the company's Wiki were developers. What about Product Managers, BizDev people, etc? Do you expect everyone at the company to use git and work with markdown? (Don't get me wrong, I wish everyone did. But knowing people in these roles makes me think this would never happen)

londons_explore 6y ago
The solution to this is to make a UI which can be used like a wiki, but in fact creates a git commit for each edit. Allow documentation-only changes without reviews or pull requests etc. Still use ACL's in the monorepo so that people can edit their own documentation with a single click, but to edit another teams docs requires some kind of pull request/approval from that team. Create a culture that code changes must have accompanying documentation changes, and that any substantial code change without documentation changes needs a good reason. Then everyone can use the tools they are familiar with, and still get all the benefits of history and always-uptodateness.
tln 6y ago
I may be in an unusual position of being able to dictate this but I always push for non-coders to use git and markdown... design assets are checked in to a repo, blog posts use markdown and are pushed to a Netlify site, marketers can tweak language and images directly in our Vue app (partly chosen for Vue's fantastic accessibility), etc. TBH I have not pushed non-coders to document stuff in git / markdown, only the developers do that. Free, friendly tools like Github desktop, VS code, Netlify CMS help a ton. It also helps that marketers, designers, product managers are all technically inclined positions, where hiring smart people pays off. There's a tradeoff as it takes more time to preach and teach the use of these tools, but I see it as a good investment for workflow and in people. Being able to wrangle git is a great skill!
- scoopertrooper 6y ago
  This would be insanity in a mono repo. A developer would have to look over every PR to make sure some critter from the marketing department didn't accidentally change an important bit of code.
  - dustinchilson 6y ago
    1) You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage. 2) It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team. 3) This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.
    - scoopertrooper 6y ago
      > You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage. Hard to catch everything > It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team. I'm all for open access, but systems should have safety rails to stop people from making mistakes. This is why we have the PR process in the first place. If you have non-programmers approving PRs created by other non-programmers into repositories that have mission critical code, then you're really just asking for trouble. > This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell. My position actually straddles product and development, so I spend much more time with marketing types than developers these days. They're fine people, but they aren't as patient and detail oriented as developers and lack awareness of the dangers of certain actions. I've seen them do all sorts of crazy stuff that would throw the security team into an absolute fit if they found out about it.
dehrmann 6y ago
If you can learn pivot tables in Excel, you can learn markdown.

mancini0 6y ago

This looks great and I wish my company adopted the monorepo & bazel. The navigation to //devtools from the link you shared results in a 404 however - perhaps the tool's routing is confused by the bazel "//<project>" syntax? Maybe not as I see the url path looks correct, maybe parent directory links should not show as active if there is nothing to serve in the parent directory.

q3k 6y ago
It's broken :) This is mildly internal for now, and needs a bunch of bug fixes before release. The behaviour I would expect for this is that the 'devtools' part of the path shouldn't be clickable - as there isn't any documentation markdown in that path of the repository. I'll see if I can implement this today. EDIT: fixed.

tln 6y ago

I prefer this as well (except for the monorepo part :) ) for anything that concerns the code/app in any way. We chose Slab for our wiki partly because it can surface markdown files from github. So, the onboarding guide just links to relevant markdown files right in Slab.

malkia 6y ago

THIS ^^^ Google took this approach internally using markdown files (If I remember correctly). Perforce is also going this way - https://www.perforce.com/manuals/swarm/Content/Swarm/basics.markdown.html https://www.perforce.com/manuals/swarm/Content/Swarm/basics.... - but I wish more (right now it's only in their "project overview pages.") This allows for code reviews on the doc too, easier to auto-generate, fix, etc - than non-file interface like wiki.

malkia 6y ago
One gotcha - if your playbook is stored there, make sure it's backup'd on secure external USB drives, as the source system, or the markdown render, or something else needed to accomplish this may go down, and now you and your team/project are going to be affected. Like pre-rendered to .html, .chm, even why not pdf files - whatever it takes just to be able for your oncall personnel to read them back if need to.
- tln 6y ago
  Presumably your on-call personnel will have those repos checked out?
  - malkia 6y ago
    What if your source system goes down, can't connect to your local machine, needs to use VM - no the oncall needs to have the USB stick or more, and use it any other company laptop.
    - q3k 6y ago
      Hackdoc itself has a mode to run from a local checkout, with no other service dependencies (vs. the production mode that expects a git/grpc proxy service to access the live repository), and as it's Go it can easily be moved around as a single, relocatable binary that will run from nearly all operating systems.
q3k 6y ago

detaro 6y ago

I feel like there's a vast difference between documentation relevant to code and a lot of the stuff accumulating in a company wiki. And if you put the latter in a global path, it doesn't become magically better maintained just because your wiki is backed by a repo. Age without further context is in any case a terrible indicator of relevance. What's IMHO important is a culture of providing the context with your entries.