EEVblog Electronics Community Forum
Electronics => Projects, Designs, and Technical Stuff => Topic started by: bug13 on November 05, 2017, 09:44:23 pm
-
Hi guys
We need a better way to do our documentations, we are doing words/pdf now, store it in share folder somewhere, that's about it. What are the better way to do these?
I am thinking about setting up a internal wiki server, or use github??
What do yous guys use?
Thanks
-
Wiki sucks because it is too tedious to write and do good cross-referencing. Better have a well structured document with chapters. Like anything you make a document needs some design effort on how to organise a project into chapters the best way.
I have some limited experience with Google drive but it seems to be OK for working on one document with several people.
-
I'm currently using OneNote, which is a pretty good program to use for it, at least on a smaller scale. A lot depends on the effort you put in yourself, though, so it might not be appropriate in an environment where rules need to be enforced.
I think there's room for improvement though, so I'm eager to see what other solutions there are.
-
I am hoping to look for something for multiple projects, and search-able.
-
I am hoping to look for something for multiple projects, and search-able.
That's why I like OneNote. You can have multiple "books" for each project, which can be modularly added or removed. I just checked and there actually is a pretty sweet search function I hadn't noticed before.
-
Hi guys
We need a better way to do our documentations, we are doing words/pdf now, store it in share folder somewhere, that's about it. What are the better way to do these?
I am thinking about setting up a internal wiki server, or use github??
What do yous guys use?
Thanks
It seems that OneNote has some capabilities for project management, although I have no experience with it.
http://www.makeuseof.com/tag/can-use-microsoft-onenote-project-management/ (http://www.makeuseof.com/tag/can-use-microsoft-onenote-project-management/)
-
Wiki sucks because it is too tedious to write and do good cross-referencing. Better have a well structured document with chapters. Like anything you make a document needs some design effort on how to organise a project into chapters the best way.
I have some limited experience with Google drive but it seems to be OK for working on one document with several people.
I think a shared wiki is the greatest thing since sliced bread for system documentation. Using Confluence is the only time I've ever been able to consistently keep project docs up to date and accessible to everyone. Referencing another page is simple - it auto-completes - so you must be talking about something more complex than what I did. There might be better/free alternatives around, I've not used anything else.
The alternative is a collection of 'x' format documents scattered around - where x = some format and usually requiring some application to open it. e.g. MS Word, Visio, Excel, PDF whatever. I hate that way of working.
The people that didn't like confluence where I worked, were the ones who only used it occasionally to get information. So yeah I agree, its not ideal for non-contributors as they don't learn the system well, and/or dislike the lack of formal structure. However structure and formality can lead to rigid processes, red tape and delays, everything is a trade-off in some way... :popcorn:
-
A major downside of something like confluence would be the subscription model. I don't even want to know what happens when they fold and all of your documentation is in there.
-
Read Fredrick Taylor, the idea is to break every process, each task down into its component parts so that actions are standardized, interchangeable parts just like in machines. "Deskilling" its called.
https://en.wikipedia.org/wiki/Deskilling
A "race to the bottom".
Hi guys
We need a better way to do our documentations, we are doing words/pdf now, store it in share folder somewhere, that's about it. What are the better way to do these?
I am thinking about setting up a internal wiki server, or use github??
Great idea, go for it.
-
A major downside of something like confluence would be the subscription model. I don't even want to know what happens when they fold and all of your documentation is in there.
You can self host confluence for up to 10 users for $10. Might be a new thing, I thought it was cloud only too.
https://www.atlassian.com/software/confluence/pricing?tab=self-hosted (https://www.atlassian.com/software/confluence/pricing?tab=self-hosted)
-
You can self host confluence for up to 10 users for $10. Might be a new thing, I thought it was cloud only too.
https://www.atlassian.com/software/confluence/pricing?tab=self-hosted (https://www.atlassian.com/software/confluence/pricing?tab=self-hosted)
Yes, it being self hosted is good. Most companies with any worthwhile IP would be very uncomfortable with stuffing their IP on someone else's servers. However, you're still stuck with a monthly subscription model. If Confluence rolls over, your documentation workflow suddenly ceases to exist. I'm not sure how this software formats things, but with a bit of bad luck you're not even able to access it at all. That might sound pessimistic, but the average lifespan of IT companies and online services is really quite short. We're used to Microsoft and Google being around for ages, but those are actually very rare exceptions.
You won't have that problem with programs that are paid upfront or which use common file formats.
-
You can self host confluence for up to 10 users for $10. Might be a new thing, I thought it was cloud only too.
https://www.atlassian.com/software/confluence/pricing?tab=self-hosted (https://www.atlassian.com/software/confluence/pricing?tab=self-hosted)
Yes, it being self hosted is good. Most companies with any worthwhile IP would be very uncomfortable with stuffing their IP on someone else's servers. However, you're still stuck with a monthly subscription model. If Confluence rolls over, your documentation workflow suddenly ceases to exist. I'm not sure how this software formats things, but with a bit of bad luck you're not even able to access it at all. That might sound pessimistic, but the average lifespan of IT companies and online services is really quite short. We're used to Microsoft and Google being around for ages, but those are actually very rare exceptions.
You won't have that problem with programs that are paid upfront or which use common file formats.
$10 one-time payment
Looks like you can dump it out to XML, HTML, PDF or Word. HTML presumably means that the exported system is (statically) usable at a basic level without confluence and without needing any format conversion.
I won't go into the self-hosted vs cloud debate - aside to say that it is generally not black and white, and is simply a decision to be made based on the needs of the company making the purchase.
-
Documentation should be part of the repo containing the hardware/firmware. This implies one is using version control (e.g., git).
For best results, doc should be visually attractive. You want people to get into the habit of checking the documentation first, before asking someone for the answer--good documentation is viral. If you have bad documentation, few people will look at it and nobody will keep it up-to-date as the system changes. If that happens, it's wasted effort. Bad doc is worse than no doc.
I use LaTeX because the end result is far better than any WYSIWYG alternative. There are "packages" for flowcharts, message sequence diagrams, data structures and mathematical formulas. Plus, LaTeX and all the stuff that goes with it is free.
The project repo contains the source code of the doc itself (because writing LaTeX is almost like writing code), but also the compiled .pdf. The PDF contains a change log, table of contents and is easily searchable.
It's a wonderful thing when you can write the doc first, have your team review it, and then write the code later. Yes, it's possible. ;D
PS. My $0.02: Confluence is terrible for documentation, for a variety of reasons.
-
$10 one-time payment
Looks like you can dump it out to XML, HTML, PDF or Word. HTML presumably means that the exported system is (statically) usable at a basic level without confluence and without needing any format conversion.
I won't go into the self-hosted vs cloud debate - aside to say that it is generally not black and white, and is simply a decision to be made based on the needs of the company making the purchase.
Sorry, I totally missed the one time payment part. I was convinced it's a subscription model. It must be because you don't see much else nowadays, except that in this case it's not.
Yes, the cloud debate is to be decided by the company itself. Unfortunately, considered deliberation isn't as common as you'd suspect.
-
Documentation should be part of the repo containing the hardware/firmware. This implies one is using version control (e.g., git).
For best results, doc should be visually attractive. You want people to get into the habit of checking the documentation first, before asking someone for the answer--good documentation is viral. If you have bad documentation, few people will look at it and nobody will keep it up-to-date as the system changes. If that happens, it's wasted effort. Bad doc is worse than no doc.
I use LaTeX because the end result is far better than any WYSIWYG alternative. There are "packages" for flowcharts, message sequence diagrams, data structures and mathematical formulas. Plus, LaTeX and all the stuff that goes with it is free.
The project repo contains the source code of the doc itself (because writing LaTeX is almost like writing code), but also the compiled .pdf. The PDF contains a change log, table of contents and is easily searchable.
It's a wonderful thing when you can write the doc first, have your team review it, and then write the code later. Yes, it's possible. ;D
PS. My $0.02: Confluence is terrible for documentation, for a variety of reasons.
Like anything, it depends. We had people (non-devs) that found Confluence too complex. Version control was way beyond them, LaTeX, ya dreaming mate, you lost them with the weird capitals in the name :)
Any documentation is better than none, even if it's some Word doc that was written before the system was built and is out of date it will usually give information about the intent of the designers. Knowing the intent is often all you need.
If you are able to build off a doc then you work in a different world to me. It is certainly not possible in this job.
-
Documentation should be part of the repo containing the hardware/firmware. This implies one is using version control (e.g., git).
For best results, doc should be visually attractive. You want people to get into the habit of checking the documentation first, before asking someone for the answer--good documentation is viral. If you have bad documentation, few people will look at it and nobody will keep it up-to-date as the system changes. If that happens, it's wasted effort. Bad doc is worse than no doc.
I use LaTeX because the end result is far better than any WYSIWYG alternative. There are "packages" for flowcharts, message sequence diagrams, data structures and mathematical formulas. Plus, LaTeX and all the stuff that goes with it is free.
The project repo contains the source code of the doc itself (because writing LaTeX is almost like writing code), but also the compiled .pdf. The PDF contains a change log, table of contents and is easily searchable.
It's a wonderful thing when you can write the doc first, have your team review it, and then write the code later. Yes, it's possible. ;D
PS. My $0.02: Confluence is terrible for documentation, for a variety of reasons.
Can you tell us why you feel Confluence is terrible?
-
I’ve been using confluence for documentation for about ten years on a 200 man project. A few points to bear in mind: it’s not portable at all, exported PDFs suck and get mangled pretty bad, it’s slow, it’s buggy, structure is absolute shit, it’s expensive over time (atlassian like to bend you over occasionally), it’s pretty unreliable (notification delivery, consistency, crashes, weird browser differences and behaviours when editing) and atlassian are dicks when it comes to support. Just remember the whole thing is built on the web so there are some crazy functional compromises to fit into that versus a dedicated tool.
We use JIRA as well. That’s just as bad.
I couldn’t possibly recommend it myself. To quote our PM, he’d rather sandpaper his cock.
Really we should have gone for a DMS and proper authoring tools rather than a stirred up pot of crap (wiki).
OneNote doesn’t rate for teams either. It’s ok for single people but that’s about it. I use this for personal note keeping. The MacOS version is dire though so I tend to use the Windows one in parallels.
Edit: I see someone pointing to use source control and keeping documentation with code. Agree! Git is horrible for this though. Use subversion and tortoise SVN and it will let you merge and manage word documents fine.
-
PS. My $0.02: Confluence is terrible for documentation, for a variety of reasons.
Can you tell us why you feel Confluence is terrible?
Sure.
First off, Confluence (and wikis in general) don't allow you to produce professional looking documents. The formatting options are whatever the wiki designer decides you can use, and that's it. Wikis are good at helping you make something that's "better than ASCII" quickly, but great documentation needs a higher standard.
Second, keyword search in a PDF document is a lot more usable than picking through pages of search its from Confluence. When the search is restricted to one document, you can be sure you've found all the hits. Confluence may give you 20 pages of stuff it thinks is relevant, forcing you wade through lots of information that probably isn't actual documentation.
Third, if the thing you're documenting is under version control, then the documentation should also be under the same version control. Changes to the product/library/whatever go hand in hand with changes to the doc. Code reviews ought to make sure that the doc accurately (and completely) describes what you're building. You might even need to maintain documentation for multiple versions simultaneously. That doesn't work well with a wiki because you have to do that through hierarchy (which is painful to change after the fact) and then your search hits (see above) have multiple--possibly conflicting--versions.
Fourth: What if you don't have an internet connection?
That's just my perspective, and other folks will have theirs. Confluence is a useful tool, but as a reader I'd much rather have a PDF for reference material.
-
PS. My $0.02: Confluence is terrible for documentation, for a variety of reasons.
Can you tell us why you feel Confluence is terrible?
Sure.
First off, Confluence (and wikis in general) don't allow you to produce professional looking documents. The formatting options are whatever the wiki designer decides you can use, and that's it. Wikis are good at helping you make something that's "better than ASCII" quickly, but great documentation needs a higher standard.
Second, keyword search in a PDF document is a lot more usable than picking through pages of search its from Confluence. When the search is restricted to one document, you can be sure you've found all the hits. Confluence may give you 20 pages of stuff it thinks is relevant, forcing you wade through lots of information that probably isn't actual documentation.
Third, if the thing you're documenting is under version control, then the documentation should also be under the same version control. Changes to the product/library/whatever go hand in hand with changes to the doc. Code reviews ought to make sure that the doc accurately (and completely) describes what you're building. You might even need to maintain documentation for multiple versions simultaneously. That doesn't work well with a wiki because you have to do that through hierarchy (which is painful to change after the fact) and then your search hits (see above) have multiple--possibly conflicting--versions.
Fourth: What if you don't have an internet connection?
That's just my perspective, and other folks will have theirs. Confluence is a useful tool, but as a reader I'd much rather have a PDF for reference material.
Yep I think those are fair points. Confluence search isn't great, that's probably been my main pain point with it.
While the docs in the repo is perfectly logical for a developer, it makes it hard for anyone who isn't technical to be involved. I expect that the smaller the team is the more critical this becomes.
When you have business people into your team, then tools like Jira and Confluence become really useful as they can be quickly brought up to speed and start contributing.
They aren't perfect for sure, and I'd love some better recommendations.
-
Thank you all, I will look into different options and use the one best meet our needs.
Cheers
-
How many people need access to write/read this documentation?
Sent from my VS988 using Tapatalk
-
How many people need access to write/read this documentation?
Sent from my VS988 using Tapatalk
There will be at least two part:
- technical specs, and
- user manual
And they are project base, so it's like this:
- project A
- technical specs
- user manual
- project B
- technical specs
- user manual
- project C
- technical specs
- user manual
etc...
The overall technical stuff and user manual are the same in general, but every project will have slightly different specs and user manual that will apply to that project.
Usually the software/hardware engineers will be updating the technical stuff and user manual, and the installers will update the user manual specify to that site.
Say about 5 people will be updating different section of the documents, others will just view the documents.
-
simple html:
A huge improvement over pdf/word: no artificial page boundaries, easier / better looking formatting, links and searching work more consistenly. No binary (or non-human readable over-complicated xml) shit.
git:
Store those html files in git for excellent version control.
Systems more complex than this are most often marketing wank designed for people who don't need to use them (i.e., bosses).