CAD Forum

What is everyone using for writing manuals?

We use word for everything for our machines but typically these always end up being under 100pgs. I'm starting to compile a bunch of information that I'm sure will end up being far more than that.

I find Word to be clumsy at best to a complete and utter nightmare sometimes. Does anyone have suggestions on something better and even better free or cheap?

You might laugh, but PowerPoint can overcome a lot of what people dislike about Word. Still, I use Word for most of my writing, even with images.

Depending on what you're going to do with your manual, you might also consider Wordpress (online html/blog format). You can get a lot of plugins for it, and it does a lot of stuff.

How about a single sheet of paper with a URL and a QR code pointing to a web site? We don't have to create customer manuals here, but whenever I create documentation, I try to put it on a web page. As soon as you print something, it is out of date. The web page can always contain the latest information.

matt wrote: ↑Tue Jun 01, 2021 1:36 pm You might laugh, but PowerPoint can overcome a lot of what people dislike about Word. Still, I use Word for most of my writing, even with images.

Depending on what you're going to do with your manual, you might also consider Wordpress (online html/blog format). You can get a lot of plugins for it, and it does a lot of stuff.

The main thing I'm looking for is to be able to create a reasonable table of content to a large amount of information.

I looked at Publisher but as far as I can tell nothing is linked, granted I haven't used publisher much in the last 15 years or so. Word can do this and this is what we do for almost all our machine manuals, proposals etc. Word however ends up getting more and more unwieldy the larger it gets. I've done 50-75 page manuals in Word and it really becomes a PIA with a change on one page moving things up, down etc etc.

Something like PowerPoint or a few others seem more pointed toward "Page layout" rather than "Manual" or book writing where you have 1000 pages with illustrations for technical purposes rather than aesthetics. I looked at affinity publisher which is reasonably priced, but seems to be almost entirely for page layout.

JSculley wrote: ↑Tue Jun 01, 2021 2:22 pm How about a single sheet of paper with a URL and a QR code pointing to a web site? We don't have to create customer manuals here, but whenever I create documentation, I try to put it on a web page. As soon as you print something, it is out of date. The web page can always contain the latest information.

Not sure how that would work with multiple people adding, modifying etc etc. I would like to get this "document" to become fairly all encompassing including documentation from our "Design Standards", Instruction on program use CAD/CAM, Standard tooling, speeds/Feeds, assembly/Work instructions for jobs and on and on.

As it stands right now this information either only exists in some peoples heads or is scattered to the winds in various drives, individuals desktops and so forth.

Someone quits and the person/People following them have no documentation to follow and don't even know where to look for it. Often times they end up making their own "New" system and starting over.

I'd really like to avoid that in the future.

The more I use "Micro-sift Orifice" products, the more I hate them. The only good thing they have going is Excel and maybe PowerPoint.

Onedrive sucks out loud; when it decides to sync it will kick everything offline.
Word is way too automated for it's own good.
Outlook breaks too easily.
Teams has been a mess ever since they killed Skype.

On a positive note, LibreOffice is the next best thing. It's free too.

mike miller wrote: ↑Tue Jun 01, 2021 3:08 pm The more I use "Micro-sift Orifice" products, the more I hate them. The only good thing they have going is Excel and maybe PowerPoint.

Onedrive sucks out loud; when it decides to sync it will kick everything offline.
Word is way too automated for it's own good.
Outlook breaks too easily.
Teams has been a mess ever since they killed Skype.

On a positive note, LibreOffice is the next best thing. It's free too.

I can't even imagine doing a large manual or any type of formatted document on Word. I can't tell you how many hours I've spent fixing things that have moved because I mad a change somewhere else in a document and it affected a page 10 pages latter. The more pages the more likely the domino effect eventually blows something up.

MJuric wrote: ↑Tue Jun 01, 2021 2:57 pm Not sure how that would work with multiple people adding, modifying etc etc.

That's what wikis are designed to do.

https://en.wikipedia.org/wiki/Wiki

MJuric wrote: ↑Tue Jun 01, 2021 2:57 pm I would like to get this "document" to become fairly all encompassing including documentation from our "Design Standards", Instruction on program use CAD/CAM, Standard tooling, speeds/Feeds, assembly/Work instructions for jobs and on and on.

Yeah. That just screams web-based to me. A bunch of disparate topics with different subject matter experts.

Since I do some coding and such here, I opted to install a Gitlab server so I could manage my source code with git. Gitlab includes things like projects with groups, users and permissions, issue tracking and a wiki, which I used for exactly the kind of thing you are talking about.

mike miller wrote: ↑Tue Jun 01, 2021 3:08 pm The more I use "Micro-sift Orifice" products, the more I hate them. The only good thing they have going is Excel and maybe PowerPoint.
...
On a positive note, LibreOffice is the next best thing. It's free too.

Personally, I dislike Word the most, excel and ppt is still OK (maybe just because i cant find an alternative...)
Especially when your document grow "Large" with lots of high dpi image, word crash just too easily...
Equation is also a mess in Word.
My personally preference when it come to writing is LaTeX... (I used it to prepare all my report, assignment in my uni time).
Spent 2 weeks learning it and never regret it.

MJuric wrote: ↑Tue Jun 01, 2021 2:57 pm Not sure how that would work with multiple people adding, modifying etc etc. I would like to get this "document" to become fairly all encompassing including documentation from our "Design Standards", Instruction on program use CAD/CAM, Standard tooling, speeds/Feeds, assembly/Work instructions for jobs and on and on.

As it stands right now this information either only exists in some peoples heads or is scattered to the winds in various drives, individuals desktops and so forth.

Someone quits and the person/People following them have no documentation to follow and don't even know where to look for it. Often times they end up making their own "New" system and starting over.

I'd really like to avoid that in the future.

I would recommend using Wiki for this... If you want something more advance such as editing rights, consider using SharePoint (which is another nightmare which take time to learn and master)
SharePoint also has a wiki feature but i had never used it...

Notion is also a bit promising in creating a knowledge base

JSculley wrote: ↑Tue Jun 01, 2021 4:10 pm That's what wikis are designed to do.

https://en.wikipedia.org/wiki/Wiki



Yeah. That just screams web-based to me. A bunch of disparate topics with different subject matter experts.

Since I do some coding and such here, I opted to install a Gitlab server so I could manage my source code with git. Gitlab includes things like projects with groups, users and permissions, issue tracking and a wiki, which I used for exactly the kind of thing you are talking about.

What "Skill set" is required for people to be able to modify, add etc to a web based system. I have not done any web based stuff for a long time and everything I did was all in HTML and I'm 10000% certain that no one wants to have to do that to add/Change information etc.

The last time I did anything like this was probably back in 2000-2002 timeframe so probably none of that applies.

MJuric wrote: ↑Wed Jun 02, 2021 8:19 am What "Skill set" is required for people to be able to modify, add etc to a web based system. I have not done any web based stuff for a long time and everything I did was all in HTML and I'm 10000% certain that no one wants to have to do that to add/Change information etc.

The last time I did anything like this was probably back in 2000-2002 timeframe so probably none of that applies.

About the same as what's required to post on a forum. Here's a screenshot from my Gitlab setup:
Note the 'New page' button and the button with the pencil icon in the upper right corner. Clicking that gives you this: Most wiki software would have the same sort of setup.

MJuric wrote: ↑Wed Jun 02, 2021 8:19 am What "Skill set" is required for people to be able to modify, add etc to a web based system. I have not done any web based stuff for a long time and everything I did was all in HTML and I'm 10000% certain that no one wants to have to do that to add/Change information etc.

The last time I did anything like this was probably back in 2000-2002 timeframe so probably none of that applies.

My personal experience with web-based system is that attaching image is really a pain... Besides that it is pretty easy to pick up (as long as you don't require user to customize stuff themselves). But i do know some user say that it is challenging and the interface is lacking (especially on media wiki)

If you would like more "User Friendly" system, maybe give Notion a try? https://www.notion.so/wikis (You can just sign up and try it for free)
Notion is like a jack of all trades, I personally used it as my personal database/wiki/task management
Learning it is pretty easy (close to zero effort if you are only interested in basic function)
The lack of "Offline Mode" is a pain for a lot user (but i am fine with it) and the only complaints i have is that it do not have "simple table" function (all table is sort of a "database") You can also try sharepoint as the Sharepoint Wiki is similar to word (well depending on how u set it up, user will still need to be trained on sharepoint).
Although if you are only using Sharepoint as a Wiki, it seem to defy the purpose of Sharepoint...

JSculley wrote: ↑Wed Jun 02, 2021 9:11 am About the same as what's required to post on a forum. Here's a screenshot from my Gitlab setup:

image.png

Note the 'New page' button and the button with the pencil icon in the upper right corner. Clicking that gives you this:
image.png

Most wiki software would have the same sort of setup.

Interesting Jim. I was going to suggest LaTeX...and it's a good option, except for the multi user part. That would take some setup that I'm not as familiar with...It can be done, but now you're not only talking about LaTeX training, but setting up an environment. Definitely doable and would get you a document that meets all of the requirements, but there's also a lot of work and discipline involved.
At work we publish a set of Standard Specifications. Last iteration was a mess of word documents that had to be kludged together at the end. For that I think LaTeX would be great option. But another engineer showed me another state (it may have been FL) where they used the wiki format for there standard specs. It solves all kinds of problems. For example if a project is underway under the 2021 version that one is accessible. Then when a 2022 project gets underway the 2022 version will also be available...all online all the time.
So, I'm inclined to agree with Jim for something like this.

JSculley wrote: ↑Wed Jun 02, 2021 9:11 am About the same as what's required to post on a forum. Here's a screenshot from my Gitlab setup:



Note the 'New page' button and the button with the pencil icon in the upper right corner. Clicking that gives you this:


Most wiki software would have the same sort of setup.

Thanks All,

That gives me some things to investigate.

The interface is going to have to be fairly luddite as my goal would be to have it "Company wide" and to be able to have an interface that everyone can add/Modify with proper permissions. For instance I would like to get to a level where the operator of the machines could add notes to work orders/Work instructions on things that are "Special", like "Had to run tool XXX at slow RPM on this part because...." or something of that nature.

Then at some future date when the part is ran again by someone else because the previous operator got hit by a bus they can pull up the work instructions, see the set up, tools used and the note.

mattpeneguy wrote: ↑Wed Jun 02, 2021 9:27 am Interesting Jim. I was going to suggest LaTeX...and it's a good option, except for the multi user part. That would take some setup that I'm not as familiar with...It can be done, but now you're not only talking about LaTeX training, but setting up an environment. Definitely doable and would get you a document that meets all of the requirements, but there's also a lot of work and discipline involved.

Multi-user for LaTeX is tough. Training and convincing people to use them is even tougher.
I had tried to convince all my friends/assignment member in my 4year uni-life to switch to it.... with 0 success rate... (in the end i just take their word file and transfer the content into my tex file)

LaTeX stand strong in academic research and publishing, but i rarely see people used it for work.
How i miss the good old day of using LaTeX without needing to worry that my Word will crash.

I've done a few operators manuals over the years and I prefer to use Microsoft Publisher, Microsoft Word sucks for a manual, add a picture and there goes your text, change the format of the picture and here comes your text all over the place. Try Publisher, Text boxes, Picture boxes, easy peasy.

JSculley wrote: ↑Tue Jun 01, 2021 4:10 pm That's what wikis are designed to do.

https://en.wikipedia.org/wiki/Wiki



Yeah. That just screams web-based to me. A bunch of disparate topics with different subject matter experts.

Since I do some coding and such here, I opted to install a Gitlab server so I could manage my source code with git. Gitlab includes things like projects with groups, users and permissions, issue tracking and a wiki, which I used for exactly the kind of thing you are talking about.

So I've been poking around most of the morning and someone mentioned this tool that we have, but not many use it. I've just started looking at it and it looks like what I want but wanted to see if anyone else had any thoughts or experience with it.

https://www.knowledgebase-script.com/

@MJuric I was gonna suggestion Affinity Publisher because I thought you meant Technical Manuals like installations guides or manufacturing instructions. Looks like you are doing user standards, SOPs, etc. We use Word for this, but we don't put everything in one document. We create a separate document for different areas and processes. They are stored in PDM and are workflow controlled and searchable (keyword and content). You could create a table of contents Word document with hyperlinks.

This allows multiple people to work on the separate documents. And our PDM workflow insures the company is seeing the "Released" versions only (except for our standards librarians).

jcapriotti wrote: ↑Wed Jun 09, 2021 1:31 pm @MJuric I was gonna suggestion Affinity Publisher because I thought you meant Technical Manuals like installations guides or manufacturing instructions. Looks like you are doing user standards, SOPs, etc. We use Word for this, but we don't put everything in one document. We create a separate document for different areas and processes. They are stored in PDM and are workflow controlled and searchable (keyword and content). You could create a table of contents Word document with hyperlinks.

This allows multiple people to work on the separate documents. And our PDM workflow insures the company is seeing the "Released" versions only (except for our standards librarians).

I'm doing both and hooking it all up to a company wide knowledge base. For instance one of the things I want to organize and get on the knowledge base is our Design standards book. Couple hundred pages that is currently broken down into single multiple page Word documents that are filed in various directories label A-Z. I'd like to get that all into a single navigable document and then link that single document to the knowledge base.

I also have a few rather large "Instruction documents" and of course we are already doing operator manuals etc in word and it sucks.

@MJuric In that case I would go with Affinity Publisher as that's what its designed to do. It's their version of Adobe InDesign which we use in house to do large manual layouts. Hard to beat $25 ($75 if so want the whole suite).

Here is a rather long tutorial but it covers a lot of functions. The text flow is cool.

It depends what I'm working on.

I use words for most "manuals" I create, but excel is also another alternative I use when creating checklists for examples. I like all the little things I can do with Excel, just don't like the whole "layout", how you can't have it somewhat paginated like on Word.

Some things I create on SolidWorks, design criterias for example. I do the drawing using existing assemblies and then annotate it and add the desired dimensions.

Does anyone have any experience with SE 3D Publishing/Illustrations? From what I see it looks like a good option for make interactive instructions/SOPs. It would probably be overkill for a manual but I would be very much interested in using it for Instructions/SOPs.

Edit: Currently I make a drawing of the assembly with annotations, label all of the Drawing Views, then I make a set of instructions using Word and refer to the Drawing Views rather than using pics (I'll still use pics where I can't illustrate it with CAD.) Using SE 3D Publishing or something similar would keep everything in the same document, you could make animations and you can use interactive BOMs.

Pinging the SE gurus:
@matt
@Imics13
@Ry-guy
@TusharSuradkar

My user guides do not exceed 5 pages, there are more drawings than text, I use sw drawing for magic, I rarely use world sometimes inkscape.

Zhen-Wei Tee wrote: ↑Wed Jun 02, 2021 9:17 am If you would like more "User Friendly" system, maybe give Notion a try? https://www.notion.so/wikis (You can just sign up and try it for free)

Hey @Zhen-Wei Tee , Thaks a lot Mate!
I've been reviewing this app for two days. I really like. equipped, talented, aesthetically pleasing. It's like a private website for me.
I was using google keep, will try that too.

Jaylin Hochstetler wrote: ↑Wed Jun 09, 2021 4:02 pm Does anyone have any experience with SE 3D Publishing/Illustrations?

Once long ago, I bought and implemented a PDM package called Product Center. It't a little obscure but one of the things I loved about it was that the company used their own software in their business. They used it as a CRM and support log. So within the company, almost everybody knew how to run the software as well as its strengths and weaknesses. That spoke volumes about the software.

I've seen the stuff SW and SE use for creating technical documentation (training and help), and in both cases, it's ROTFLOL kind of embarrassing. Pre-2000. Looks like Windows 3.1 kind of stuff. If these companies don't think their own technical publication software is better than embarrassing old crap, then why would I? Personally, for this reason alone, I've never even looked at either one.

I was contracted to write some training stuff for SW and I proposed we used the Composer thing, and was met with a wall of silence. So something is wrong. Either all the people are stupid or the software sucks, and I know the people aren't stupid.

jcapriotti wrote: ↑Wed Jun 09, 2021 2:23 pm @MJuric In that case I would go with Affinity Publisher as that's what its designed to do. It's their version of Adobe InDesign which we use in house to do large manual layouts. Hard to beat $25 ($75 if so want the whole suite).

Here is a rather long tutorial but it covers a lot of functions. The text flow is cool.

Affinity Publisher can't span columns. That may or may not be a deal breaker for some, but for what I need it currently is a problem.
Here's the discussion starting 3 years ago:
https://forum.affinity.serif.com/index. ... n-columns/

matt wrote: ↑Thu Jun 10, 2021 10:01 am Once long ago, I bought and implemented a PDM package called Product Center. It't a little obscure but one of the things I loved about it was that the company used their own software in their business. They used it as a CRM and support log. So within the company, almost everybody knew how to run the software as well as its strengths and weaknesses. That spoke volumes about the software.

I've seen the stuff SW and SE use for creating technical documentation (training and help), and in both cases, it's ROTFLOL kind of embarrassing. Pre-2000. Looks like Windows 3.1 kind of stuff. If these companies don't think their own technical publication software is better than embarrassing old crap, then why would I? Personally, for this reason alone, I've never even looked at either one.

I was contracted to write some training stuff for SW and I proposed we used the Composer thing, and was met with a wall of silence. So something is wrong. Either all the people are stupid or the software sucks, and I know the people aren't stupid.

I participated in a demo of Composer here a while back and wasn't too impressed. It is pretty much a screenshot software on steroids. The thing that really sucks is they still use Word for the instructions themselves.
The procedure for instructions was

1. Bring in the SW model
2. Make Exploded Views, etc.
3. Save out Vector and Raster images using a naming scheme
4. Bring them into you Word doc as linked

I was pretty impressed with this video SE 3D Publisher https://solidedge.siemens.com/en/resour ... olid-edge/. Then again it is a marketing video....
And BTW SE 3D Publishing is $400 cheaper per year subscription than Composer.