Just trying to learn from others I figured I would ask what are some items where you feel like the official documentation may be inaccurate or incomplete and what would your edit be if you had a “magic pen”
I know one of my pet peeve in this category was (it got fixed in the help documentation of FM14) the fact that get(accountname) returns the account name as it was typed by the user at login (matching upper/lower case), not how the account is defined in the file’s security. (I still don’t understand why it behaves like that, but that off topic)
So please share, I’m sure we can all learn some gems that would be hard to uncover otherwise.
Unfortunately the whole IT industry suffers from an overestimation of their customers’ core skills and documentation always commences at a level starting too high, resulting in many people having to cross-refer so that they can then understand the help being offered.
Documentation as a rule is very poor and examples given are so simple as to be useless - take SSL certificate management as an example.
Hence the value of communities, both official and unofficial.
Documentation is written for those who already know .
Hyperlinking allows for structured documentation. The starting point may be a function’s definition. From there we could have a sample code branch (commented samples, of course) and a ‘known issues and workaround’ branch. Some ‘design limitation and pitfalls’ information would also be helpful. With that, also beginners could start out with a function name and find all information they need. Certainly an open list of things that could be presented in meaningful context to developers of all levels of proficiency.
Wikipedia gives us the definition of the term Official. An official is a person who holds an office within an organisation. This organisation can be a company or an association or even an informal organisation (like this forum).
The organisation that is running the forum makes the distinction.
There are manufacturer-, distributor-, publisher-, developer-run and forums run by other groups of interest. None of them is less ‘official’ than any other and each one has its raison d’être.
Writing this because I am not comfortable with the distinction official - unofficial.
This distinction only makes sense to my in terms of government/authority(official) - private/commercial (unofficial). Maybe a déformation professionelle from working many years in a regulated industry.
I’m open to changing the title if it means it is both more accurate and easily understood by everyone. What do you suggest as a replacement @Torsten ? I am not specially familiar with that end of things and felt like it was close enough to do the job. But I’m always seeking to improve.
When documentation is issued by the manufacturer, I would simply call it ‘Product Documentation’.
This is the primary source of documentation. Documentation issued by others is secondary source of documentation.
So I would go for ‘Product Documentation Issued by the Manufacturer’. Replace ‘manufacturer’ with the company name for convenience.
Sounds a bit dry but I like to stick with technical terms.
@Torsten, I updated the title to reflect that, hoping it aligns with your suggestion while sounding a bit less dry than Product Documentation Issued by the Manufacturer
Data Viewer
Debugger
DDR
XML report gotcha to get more than structure.
Developer’s tools tab.
It took me 2 years for learning to use the data viewer (and a few more months to use it intelligently). By observing John Renfrew use it at CDFMQ 2018.
Learned to use the debugger properly and usefully 2 weeks ago, 38 months after getting acquainted with FileMaker during a coaching session.
as I was working on a project were IBM was part of, one of the IBM guys said ‘if there is a complete documentation for a software, this software must be obsolete’
.