We're currently using a Wiki, but we're not happy with the manual structuring required and aren't very fond of the Wiki Markup. As a second option,...
For further actions, you may consider blocking this person and/or reporting abuse
I really like GitBooks. (see: gitbook.com) It reminds me of an old school SOP when they lived in three-ring binders and had handwritten content pages in the front.
Not sure what 'hosted on premises' means, so there's that :D
It means that it should be hosted locally somewhere in our local network. So no cloud services or something, we don't want to put that kind of data on other people's servers.
All GitBooks are essentially just Git repositories, which can be self-hosted. If your organization requires it to be hosted on premises I suppose you have a self-hosted Git service like GitLab.
In that case, GitLab Pages plays well with GitBook using GitLab CI. Otherwise, you can set up some CI/CD pipeline that automatically builds your books for you.
Do you use GitBooks throughout the entire org -- i.e. sales/marketing docs or strictly for technical documentation?
For everything!
We use Confluence (along with JIRA and BitBucket Server) and it's a bit of a clusterfuck. No one really uses Confluence because it's extremely hard to find anything when there isn't anyone managing it and keeping it organized. It's a repository for a lot of documentation. Often times JIRA tickets and git commit messages are a far better source of documentation in the code than Confluence.
Other downsides to Confluence are cost, maintenance and lack of standard (i.e. markdown) support.
This says a lot about other options though: Everything else we've considered doesn't do any of this better.
Our Confluence turned into a total clusterfuck until we realized the importance of wiki gardening. I had to put on a bit of a deletionist hat, which helped, but the real win was developing a standard page organization format for documentation. Every project is laid out in the same way, with the same type of documentation in the same place.
Since search sucks soo bad in Confluence, the rigid layout guidelines made it useful again.
We also use Confluence (along with JIRA) and I agree that JIRA tickets and git commit tend to be a better source of doc to understand what components do. Confluence seems powerful but it's not intuitive and requires time to manage/organise.
Our team uses Confluence within the Atlassian suite. Works fairly well for the intended purpose, and it's easy to use. Creating a page is more like creating a word doc than a wiki. I like it better, but those are the only two solutions I've ever used. ¯_(ツ)_/¯
Same here, confluence does the job..... I wish they improved their markdown support though
I miss their wiki markup support. They seem pretty investing in their wysiwyg editor... :(
We started with a wiki (since we were on GitHub, we used the one provided with our main repo). We eventually switched to using a separate repo containing only markdown files named
metafor all of our documentation, including research, best practices, corporate how-tos like expense reporting, time off protocols, etc. We even had a page dedicated to the memes we use in chat, so new team members could figure out what the heck was going on.We found using a markdown repo gave us a few advantages:
Disadvantages:
You mentioned some non-technical documentation is in the repo too -- how have non-devs managed to deal with that? Do your non-technical teams use a different system for documentation?
Since we were a GitHub shop, we just had the greater product team (product management, customer success, etc) set up GH accounts, so that any URL to documentation was accessible. That at least gave everyone read-only access to the docs. We did end up teaching some of these people enough git-fu so that they could contribute, as part of their professional development, and that was well-received. But I did feel this setup was more dev-centric than I would have liked, and it ended up duplicating some information that was contained elsewhere, like in the employee handbook. But I have a violent allergy to both SharePoint and Confluence so this worked well enough for us.
The problem with wikis is when you want to relate your notes to your code (and ideally, that's what you want to do).
I created Code Story to address this issue. Have a look ! I'll post about it soon.
Our team of approx 60 devs are using Atlassian Confluence. The choice was really simple, since we had an existing wiki, and our company moved to the Atlassian suite of products.
We've also focused on documentation that describes behaviours of systems and across systems. So most of it actually reflects what the intent of the code is. Capturing intent and being able to track decisions / choices and motivations over time has allowed us to actually have useful documentation that allows the next developer / tester / ops / whoever to get up to speed relatively quickly.
It's also a wonderful source of group decisions / goals when starting projects, that give a lot of context into why code has been written in a certain way.
I'm not a huge Jira fan, but Confluence is super easy, straight forward, and quite intuitive in comparison.
We have tried with google docs, but that's never worked well enough. too ad-hoc, hard to navigate and discover things in the structure, and... It almost hurts to say it...Confluence has great Jira integration that makes life easier for us 😁
Right now I'm using Notion for personal notes, dumping some stuff into the github wiki, and putting stuff I may need to share into onenote (because the rest of the team is using it). Previous job we used 100% confluence, which was ok because it integrates well with jira.
All I want is a reasonable editing interface that handles markdown-like formatting, including easy code formatting, and a way to share with a team. Bonus points for easy linking to github/asana issues, even if I have to write the macro/shortcut myself. Notion is ok, but is really opinionated about how you'll structure your text and has a couple quirks/bugs that deeply irritate me.
We're using confluence with a template page hierarchy. Something like:
The latest version of Confluence lets you copy the whole page hierarchy and do a find/replace in the title of the pages.
I'm not sure if Confluence counts as a 'large-ish setup'. It requires a database, and it is a java webapp, with all the infrastructure that implies. It hasn't been too bad for our team, though. On the positive side, it gives you a wysiwyg editor
Day job: team foundation server, team build, visual studio, sharepoint, office 365, onedrive. The integration between all the tools is very well done. Visio diagrams for architecture. If we were a small business, I'd push for visual studio team services.
Other job: confluence, gitlab, jira. Has giant gaping holes where features should be. Terrible integration. Just terrible.
Edit: doesn't really answer the question. A well architected file structure is great with appropriate office doc types, sharepoint as a UI with all the other integrations. The other company doesn't do much when it comes to documentation.
What are the gaping holes? I'm in a confluence, jira and kallithea shop, and maybe I just don't know any better, but I haven't noticed any gaping holes.
I would like organizing documents to be easier, so I really want to know what I'm missing!
Probably just the company. Their jira instance looks like a combination bug tracker and project management tool. No test case management (admittedly, after a quick googling, I see there are plenty of add-ons that make me wonder why none are installed). Also no source code integration. I believe there is a gitlab integration available for jira - I don't think they have it set up. But even if it was set up, there's no IDE integration for updating an issue and triggering the workflow. Are there only "issues" in jira? I don't see different issue types with different workflows.
Their confluence looks like a social platform for IT rather than a project document workspace. I will say that it has a nicer UI than sharepoint. I'm not sure how it handles document versioning, checked-in/out states - I don't use it that much. Also, I don't know if it's possible to link confluence documents to jira issues (I see you can attach documents to issues, but not link unless you manually paste a path in there), I can with my TFS work items and Sharepoint docs.
Regardless of the misuse of the applications, the integrations overall are too weak for me in this stack. I want something like in this diagram (assuming a work item has a time element for project management purposes): i-msdn.sec.s-msft.com/dynimg/IC749...
There are JIRA integrations for intelliJ and eclipse, but you have to set those up, and have your source control integrated too...
JIRA lets you define as many issue types as you want. I think "Bug" "Improvement" and "New Feature" are the defaults, but my shop has a number of other types. Likewise with workflow, you can make per-project, per-issue type workflows. I believe you can add as many workflow states and transition as your heart desires, but again, it's manual work.
Thanks for the MS tool rundown, I appreciate it!
We use confluence. The hardest part I found about documentation is writing it. To encourage continued documentation, I have suggested in the past to at least create a page in your tool, prefix it with "DRAFT" and at least do a brain dump or even copy paste from past conversations. At least that way, the knowledge isn't lost. I've found that has time goes by, I eventually go back and start cleaning things up and eventually end up with some pretty clean documentation.
For personal documentation, I follow the same thing but with evernote.
By simply having the data somewhere, it can at least be indexed and searched even if it's ugly.
We're using DocFx as a tool for building our Wiki pages. It supports Markdown. dotnet.github.io/docfx/ Basically, we host our markdown pages in local GIT, and then build the static site from command line.
We're using Quiver in my research lab. It meets all of your requests and then some:
The downside: it's MacOS only.
Quiver looks really solid, but I'm kind of flabbergasted by their choice of only offering MacOS. That seems like a real problem on lots of fronts. I know cross-platform is easier said than done, but it seems like a possible deal-breaker. And I say that even though our whole team happen to be MacOS users.
Great question!
I use AsciiDoc (methods.co.nz/asciidoc/) to write my docs and treat it as code (search for "docs-as-code" or "docs-like-code"). So I just store it along with my code or in its own repository if it belongs not directly to the code or is written before you code like architecture docs.
Most git frontends like bitbucket and github support the direct rendering of AsciiDoc, but I've build up a toolchain which helps me to maintain my docs. It is called docToolchain and can be found on github: github.com/rdmueller/docToolchain
It helps me to automatically update diagrams, render the docs as PDF or publish it to Confluence. The Confluence feature is IMHO the best - it allows you to let people read your docs in a wiki while you maintain them in Git.
A presentation on the thoughts behind it can be found at speakerdeck.com/rdmueller/thhg-to-...
We have an internal WordPress blog for explaining algorithms, new functionality or research, but it's not the best solution for all developers as some find it very difficult/cba to find the time to blog their ideas/findings. I personally use Evernote for my own notes and share these with people when they happen to work on a piece of code which I've worked on or had some ideas about alongside the WordPress blog. But we don't have a one size fits all solution... Looking forward to seeing others input :)
We use yard (a ruby gem) to generate code documentation and also static project overviews, runbooks/workflow guidelines, many howtos and troubleshooting guides.
This works well as all changes to documentation are in version control and have to be reviewed.
The tool generates static HTML which makes the deployment of the docs pretty straightforward.
And then Google Docs/Drive for keeping meeting notes or collabarative planning of features. Google Drive makes file management hard somehow, but the search always works.
We are using GitLab and with the latest CE it also has GitLab Pages included. Which is like github pages.
I also loved the idea of runbooks, which is also from GitLab <3 Where you collect all valueable information in one place.
So we have one repo which covers infrastructure, smaller howtos, information about staging, deployments, styleguides, coding conventions, etc. in that repo.
For static generation we use GitBook with the FAQ theme. It's it really nice, because of the GitLab CI runner you only need to push your markdown files and it will build it.
However we also have some project related things in Confluence. Which is a bit, clumpy for my taste. It got a hell lot of features, but is kind of slow and... does not feel that good.
My only complaint with OneNote shared Notebooks in they are very slow in-browser, otherwise I love them (My robotics notebook is public for instance) . I like GitBooks as long as everyone involved knows git (you could host git on-premise, I've never done it so I can't speak to the ease of it)
My colleagues in technology and I like to keep all the docs with the code in source control (preferably in Markdown, Gherkin or other change-control friendly formats), however we're a multi-stack shop due to a number of acquisitions, legacy technology stacks, etc, so we have multiple solutions:
1/ Almost everything in TFS/SharePoint, now migrated to VSTS in the cloud (not good for the OP), aka the full Microsoft solution - this works pretty well, including less-techie access and editing via the VSTS web GUI for requirements management, design reviews, etc. Project control is via Aha*, which integrates with VSTS ticketing.
2/ The Atlassian solution, Confluence + Jira + BitBucket Server, also being migrated to cloud versions (we like the cloud!) - thus far unable to hold confluence pages in BitBucket, so not really connected together, but a good UX with cross-referencing, and excellent for less-techie access. Aha again integrates with Jira for project control.
3/ The random document clusterf*ck - not my favourite approach but still rather popular, especially when documents or information are sourced from outside the business and helpfully emailed round the team(s), or dumped on a non-versioned shared drive (we're trying to kill this!). Some sanity is usually created through a common project document structure, and encouraging outsiders and their internal reps to feed into Aha as a common information point.
We use System Architect, but most people hate it. If you have a decent Wiki like Confluence, you have a decent environment to architect in. Gliffy or PlanUML for diagrams, and normal wiki for the rest. I hardly ever drop into markup.
Following. I've helped initiate a new set of docs at my company over the last couple of weeks, and we're currently in this dilemma. We were using Confluence to keep important info, but it just feels so detached from our workflow. We've started including a more informationally verbose readme in our project files, and eventually decided to build our docs in ButBucket. I don't know if it will stay that way, as we're still discussing whether or not the Project Managers should learn Markdown and the basics of Git, in order to maintain docs from their end. I'd love to eventually see a better solution, such as a front end wysiwig that converts rich text into MD, and ties into a repo.
I've honestly yet to find a solution as good as markdown files in the code repository for technical docs and google docs for "businessy" type of documents, meeting notes, estimates, etc.
I try to keep architectural docs right with the code, then process them to PDF with pandoc if there's a ever a need to share those outside the team.
We use confluence for documentation. Now we have a single point for a documentation. For our supporter we use SharePoint with the Integrated search. Because this is times faster as a huge confluence database search.
The first place I am searching for docs is the place where the project is. In Version control. We currently are using a mixture of internal wiki and OneNote. But we are slowly migrating to Markdown files stored next to the code.
notion.so is pretty great for me and gets a lot of updates! once you give it a hour or two and sort of absorb the 'block' structure the slash commands and nested pages + columns is quite an amazing feature! it all depends on what kind of documentation i'm working on though, for code I like to just use a pattern library, for text dropbox paper is very nice.
I keep them in my github repo. I create user stories in markdown files and organize my work with imdone-atom and import my TODOs into github issues with imdone.io. It keeps me from context switching while I work and keeps my issues in sync with my TODO comments. You can read more about it here
We spread it around multiple, disparate systems so that no one can ever find what they need. The best way to find information at my current client is to email 30 people for days on end.
Confluence...'cause Atlassian owns our soul.
Spit, duct tape and Confluence. Some days I think the duct tape wins.
"What are you talking about?" -scientific programmer
We're using google drawings for diagrams and charts, and a wiki(mediawiki) for the docs.
We keep it in our source control
Depends some use share point, one drive in MSFT world.
Nowadays confluence
Redmine, project's wiki
Dokuwiki. dokuwiki.org/ - Even if it's what you aren't happy with it, it can be extended with a few modules.
Google Drive! But now that I learned about Quiver in this thread, I'm checking it out. 😂
Redmine. Has a wiki, git integration, file storage and easy to use project management.
I use a wiki for each project.
still a newbie, so this hasn't come up for me yet, but would love to see what everyone else is using, for future reference!
Any research kept in a NOTES.md file in the repo, because I don't want to spam the README.
Gitlab ticket or Gitlab wiki pages. Uses Markdown, lies in same project, can be linked form other Issues/wiki pages.
Google Cloud, top tools 👌
I've never been happy with anything I've tried, so would love to hear other people's thoughts and opinions on this
I've used github's wiki in the past but eventually information would also end up on google drive. Would love some insight on this question as well!