11 Replies Latest reply on Aug 16, 2016 10:47 AM by TonyWhite

    Add an area for Product Documentation discussions

    TonyWhite

      It would be a good idea for the FileMaker Product and the FileMaker Platform if FileMaker Inc. were to do the same thing forProduct Documentation as has been done for Product Issues and Product Ideas.

      FileMaker documentation comes in many forms, and in general does a good job of covering a wide and deep platform. That said, there are many parts of the documentation that are incorrect and/or incomplete. Currently, if any developers sees a mistake in the documentation, the suggested protocol is to submit a correction to a web form. There is not much incentive for most developers to do this. Has someone else already taken the time and the energy to submit a bug report on the documentation? Would I be wasting my time and energy? Will I be able to get feedback from other developers?

      FileMaker made a wise decision in setting up the Product Ideas area on FileMaker Community. This has harnessed the energy and the collective knowledge of the FileMaker developer community, and has been good for the FileMaker Platform.

      Likewise, it would useful to have an area for Product Documentation. This could be a simple as having a parallel post/discussion thread on FileMaker Community for each documentation item.

      Key areas of FileMaker documentation include:

      1.1 The knowledge base articles Here, for example, are 2 articles where I would like to both give and get feedback (there seems to be a gap for FM 13):
      https://help.filemaker.com/app/answers/detail/a_id/10678/~/using-screen-stencils-to-design-ios-friendly-layouts
      http://help.filemaker.com/app/answers/detail/a_id/14552

      1.2 It would be good if there was a twitter feed for changes and new KB pages

      2. The white papers: Version numbers would be useful. I am not sure if there currently is a method for summiting corrections and/or suggestions.

      3. The FTS training material: For example, perhaps there are some keyboard shortcuts in the script workspace that are undocumented there.

      Better documentation leads to better FileMaker "apps" which lead to a stronger FileMaker community.

      Tony White

        • 1. Re: Add an area for Product Documentation discussions
          beverly

          Thank, Tony! It might be beneficial to show a "format" for submitting documentation comments. (add to the list!):

           

          Title of document

          Name of document (if different from Title, such as with .pdf)

          URL (if any) to full document.

          ________

          Page number

          Paragraph number (on page)

          Section (if any, especially if no page)

          URL to direct link (including hash, if any) of the section

          ________

          Quoted text of paragraph/sentence to be discussed

          Image description (if any) to be discussed

          --------------

          Correction and/or expanded description or example

          ???

           

          beverly

          • 2. Re: Add an area for Product Documentation discussions
            beverly

            Also, don't rely on Twitter or FB for 'feeds'. not everyone gets these.

             

            And if any particular documentation does get updated because of the discussion, then it should be noted (sort of like "Correct Answer") in the discussion.

             

            Another point to note is that URLs can change, so as much information (title of the page, etc.) should be described to get to the documentation (if online, such as Help) in the discussion.

             

            beverly

            • 3. Re: Add an area for Product Documentation discussions
              TonyWhite

              Thanks beverly,

              Following is a method that we use with one of our clients to submit suggestions: Green means add text. Red means remove text. [Purple is a note.] Blue is a link.

              Use Case:
              To support our FileMaker development work, we would like to have a better understanding of FileMaker Go screen sizes and usable areas across multiple versions, devices, etc.

              I am finding the 2 KB articles that I mentioned in my OP to be confusing and incomplete. Therefore I will use one of them for both real world suggestions and as an example of a method for suggesting additions and deletions.


              Using Screen Stencils to design iOS friendly layouts
              https://help.filemaker.com/app/answers/detail/a_id/10678/~/using-screen-stencils-to-design-ios-friendly-layouts
              [begin excerpt]
              This article is for use with versions of FileMaker Pro and FileMaker Go prior to 13.0 [clarify: does this include 13? If not add a page for FMG 13].  If you are using a newer version of FileMaker Pro and FileMaker Go, you will want to refer to this article instead. [This goes to FM 14+...see note above, same para]

              Screen Stencils [add link: https://help.filemaker.com/app/answers/detail/a_id/10094/related/1] in FileMaker Pro and FileMaker Pro Advanced [added in version QQQ] aid in the design of specifically sized layouts - including layouts sized for use with iOS devices.  These guides are just that - guides as to what will and will not fit on a layout based on the size(s) selected.  These guides in no way prevent you from creating a layout beyond the bound suggested by the on-screen guides.

              Screen Stencils take into account the dimensions of the screen but do not reflect the true dimensions of the usable layout area.  For example, Screen Stencils do not take into account the displaying of scroll bars, Status bars, toolbars, and various other screen elements.  Because of this, the useable layout space as defined by the screen stencils is less.

              [add a .jpg of an iOS screen, 1 for iPad and 1 for iPhone? With “call outs” that show the Toolbar, Status Bar, Record Selector and Vertical Scroll Bar. Not the changes to these across FMG versions
              See the “cheat sheet” that Kevin M. Cunningham did http://www.kcunning.com/consulting/documents/FMGoCheatSheet_iPad_v1.pdf for inspiration]

              [if one person does a good diagram of iOS screens... 1,000’s of developers will benefit]

              [add note that you can make the record indicator go away as of version 13 (confirm version). Link this to the docs for the new Theme and Style options in FileMaker 13]

              [Meta: Strengthen the flow of changes and improvements made by the software engineers to changes and improvements in the customer facing documentation. If a feature ships (big or small) and developers do not knows about it, did it really ship?]

              [Perhaps list the relevant Script Steps, Function and Script Triggers with links]

              If you want to create an iOS friendly layout, a design best practice is to minimize the amount of horizontal and (sometimes, but not always) vertical scrolling required to interact with your layout.  For example, if you had a list of items you wanted to display that would require you to scroll up and down through records, you would want to minimize (or eliminate) the amount of left to right scrolling that is necessary to view the list to provide the best customer experience.

              The follow tables describe the actual usable layout area for iOS devices (in points) and can be used to setup a custom Screen Stencil if need be in FileMaker Pro and/or FileMaker Pro Advanced .
              [end excerpt]


              Please note that I have not tested the math on this page and am not vouching for accuracy by not commenting at this time.

              Hope that helps.

              Tony White

              • 4. Re: Add an area for Product Documentation discussions
                TSPigeon

                Tony White:

                 

                Thank you for your post.

                 

                I have forward this suggestion on. If I receive any information I will post back here.

                 

                TSPigeon

                FileMaker, Inc.

                • 5. Re: Add an area for Product Documentation discussions
                  TonyWhite

                  Hi TSPigeon

                   

                  Thanks. Here is more for you and any other developers "working the platform".


                  Dial Phone is likely wrong here (missing iOS)...
                  https://help.filemaker.com/app/answers/detail/a_id/11708/related/1
                  ...and correct here...
                  https://www.filemaker.com/help/14/fmp/en/html/scripts_ref1.35.157.html
                  In any case...inconsistent...can not both be right.

                  Dial Phone is an example of why you should add Mac vs. Windows to your detail pages. You have it on your list view!

                  It would be a good idea if these 2 documents came from the same data source. A FileMaker database would be a perfect fit.
                  That would help with accuracy and consistency.

                  I recommend you use FileMaker to generate the content of the pages.

                  Hope that helps.

                  Tony White
                  http://www.twdesigns.com
                  http://FileMaker-Fanatics.com

                  • 6. Re: Add an area for Product Documentation discussions
                    scottworld

                    Clearly, documentation is the weakest link in FileMaker's offerings. And astute developers are constantly stumbling upon omissions or mistakes in the documentation.

                     

                    But poor documentation also hurts newer developers, because they get misled with wrong information, or they end up misunderstanding key concepts.

                     

                    SO HERE'S AN IDEA:

                     

                    Why doesn't FileMaker Inc. open up the online documentation as a FileMaker Wiki instead? That way, all of us developers can submit our own changes & additions in real time to FileMaker's documentation, and we can all enhance the documentation as a community?

                    • 7. Re: Add an area for Product Documentation discussions
                      TSGal

                      scottworld:

                       

                      I have sent your "IDEA" to the manage of our Product documentation.

                       

                      TSGal

                      FileMaker, Inc.

                      • 9. Re: Add an area for Product Documentation discussions
                        mark_baum

                        Great suggestion, TonyWhite!  Collaborative/crowdsourced documentation needs a clear goal, boundaries, and organization to work well -- all of which take careful planning -- but we'll look into this internally and consider what might be possible.  It could make a good complement to the FM Community.  Cheers -- Mark

                        • 11. Re: Add an area for Product Documentation discussions
                          TonyWhite

                          Thanks mark_baum

                           

                          For the knowledge base articles (In the short...and possibly long term) it could be as simple and easy as:

                           

                          1. add a companion page on community.filemaker.com for each KB/help/etc. article and

                          2. add a link to the knowledge base article article that points to it.

                           

                          This would leverage existing infrastructure, maintain editorial and quality control, while facilitating valuable contributions from the entire FileMaker developer community.

                           

                          Would be awesome!

                           

                          Tony White

                          2 of 2 people found this helpful