Related
Im building a toolbox for a certain branch of biology. One of the reasons Julia was chosen is its simplicity, as biologists wont be assumed to be able to write complex C-code
What I'd like to add is a way for users to share their own custom methods for others to review/verify/use, both to promote collaboration and to add a bit of sense of community
What Im sure of is that this specific demography of (mostly) biologist wont be able or have patience to fork a github project or anything that could be considered remotely complex, especially when it wont benefit them explicitly to do so
So, what I'd like to do is provide the simplest of interfaces, with the add/view options to either add a routine or view routines (along with descriptions, ratings etc)
I can only think of two ways to accomplish storing the scripts pushed by users, by having them on a server, or, more simply, using SQL
tl;dr can postgresql store scripts or is that a terrible idea
I ask, mainly because there will be 'raw data' available on a postgresql server, and I'd like to be able to keep that and the 'community methods' both in the same place for convenience sake
To summarize the discussion in the comments to this question:
Version control is an excellent solution to sharing control, but from a scientist's perspective, it can be difficult and complicated. Luckily, GitHub now offers a GUI that is easy to learn and yet retains a lot of the power of Git. For instance, GitHub allows one to edit files directly from the web UI.
We want to document a standard REST API interface which will be implemented by a number of vendors. Currently we are using Google Docs to store the specification.
Requirements (which must be common to most):
Spec history: We want to be able to reference previous versions of the specification.
Version control: We want to store the spec in version control, so that we can tag versions against our codebase and store it alongside the related
Issues: We want to allow the community to submit issues.
Community / Affiliation: We want to share the specification with a broader community, to receive validation on our approach.
endpoint validator.
Format / Tooling: We want to use a format that is easy to edit, and also publishable into an easy-to-understand form.
Potential ratification: If it's useful, it would be good to create a standard where there's a pathway for it becoming more widely adopted.
From a little research there are a few relevant standards bodies:
IETF (Internet Engineering Task Force): Mostly use the text-based RFC format, but seem to have some nice tracking tools. Generally for lower-level standards (e.g. TCP), though they've created higher level ones too.
W3C (World Wide Web Consortium): If we are publishing through the W3C eventually, it looks like we'll need to conform to pubrules.
WHATWG (Web Hypertext Application Technology Working Group): A group that appears to focus mainly on HTML5, so less relevant for a REST API spec.
OASIS (Organization for the Advancement of Structured Information Standards): Seems to be more about business abstractions on top of IETF / W3C standards.
I have looked at a few examples over the web, and note a difference of approaches:
YAML: spec history, versioned in GitHub, issues on GitHub, no apparent affiliation, uses DocBook.
JSON-LD: spec history, versioned in GitHub, issues on GitHub, W3C affiliation, uses ReSpec (also on GitHub).
JSON API: spec history, versioned in GitHub, issues on GitHub, no apparent affiliation, appears to use Jekyll and some custom templates.
JMAP: versioned in GitHub, issues on GitHub, no apparent affiliation, appears to use markdown and some custom templates.
HTML 5 (W3C): versioned in GitHub, issues on GitHub, W3C affiliation, uses Bikeshed.
HTML 5 (WHATWG): versioned in GitHub, issues on GitHub, WHATWG affiliation, uses a "proprietary language that is then post-processed into HTML" (source).
JSON Schema: versioned using IETF tooling, issues on GitHub, IETF affiliation, uses IETF RFC format.
CSS 3: spec history, versioned in Mercurial, issues inline in spec, W3C affiliation, uses Bikeshed.
For a REST API, which approach should we follow? What are the advantages and disadvantages of each?
Caveat: I was the original author of ReSpec (though maintenance has now passed on to others).
I think that at the end of the day, a lot of it boils down to your personal preferences. Both tools support your first list of requirements. Both tools have a similar feature set with a lot of overlap (but also distinct things) and in both cases the documentation may not cover that fact.
Some things that might help you choose:
ReSpec requires zero installation. In my experience that makes it easier for contributors who are relatively new to spec-writing to get started since they can just fork the repo and edit the HTML — refreshing the browser will show the edits directly. ReSpec source uses conventions beyond HTML, but it is always conforming HTML. Bikeshed requires either a working Python2 installation and it needs to be installed, or use of a curl command to the web version (but I don't think that's very convenient). To more seasoned users, that point makes no difference.
ReSpec does support batch building, there's a respec2html tool that comes with it. You should normally be able to operate it in CI (otherwise spec-gen works too).
Publican is dead, as far as I know.
If you are producing specs that are not intended for W3C, you might need to patch whichever option you pick. At that point your preference in language might be a factor.
ReSpec will not be very good at very large specifications (but for most cases it's fine).
Overall I think that's it. If you're undecided, the best thing might be for you to grab the sources of two similar specs and compare to see what you like best, and also to play at making a few small edits to both and see what's most convenient for your expected workflow. At the end of the day, don't agonise over this: both formats are HTML-based (and support embedded Markdown if that's your thing). Converting between them should you need to will likely require less time than a properly thorough investigation!
Caveat: I'm the author of Bikeshed.
As Robin said, the choice of processor is largely one of personal taste. Most of the differences in processor are minor; to my knowledge there are two major differences to consider:
Bikeshed compiles a source document into HTML; ReSpec is included into an HTML file and on-the-fly rewrites it into better HTML. In my opinion, this makes ReSpec slightly easier for casual use (nothing to install, just refresh the source document to see changes), but Bikeshed is better for the ecosystem (no "flash of un-ReSpec'd content" or "jumping spec" when you navigate to an anchor). That said, Bikeshed is easy to install locally, and a lot of people use the server version instead quite happily.
One of Bikeshed's primary features is its cross-spec linking database; it has a growing (largely W3C-centric) database of specs that it regularly spiders for definitions, and makes it very simple to link to those definitions. This has resulted in greatly improved cross-linking in W3C specs, which makes things much easier to read and follow. However, if you're not planning to link into W3C specs, or have them link into you, that's not a big deal. Linking "locally" (within your own spec) is about as easy in either processor.
So on the Bikeshed vs. ReSpec topic, a few thoughts:
When choosing software to rely on, technical superiority or feature set of a project over an other one should rarely be your deciding factor; unless of course there are specific features that you absolutely need to get your job done and that aren't available in all contenders.
Software tends to come and go. And that's true of commercial software as it is of open-source. The steeper the learning curve and the higher migration costs, the more you want to consider a tool's future when picking one.
Bikeshed's killer feature is its cross-spec linking database integration. But it's only a killer feature if you need it. I doubt you would given your current use case.
That said, because it is a killer feature for some of the more involved and Web-centric spec editing, it's acting as a magnet, pulling in key members of the community. As these members adopt Bikeshed and use it for new spec or convert existing specs to it, it increases that tool's appeal creating a snowball effect. Conversely, it makes it harder for ReSpec to maintain its traction. Having a reactive maintainer whose job it is to write specs and whose tool to do so is Bikeshed also helps.
All in all, Bikeshed has a brighter future in front of it than ReSpec does at this point. So, even though you don't need Bikeshed's extra features, its learning curve is a bit steeper and installation more involved, you might still want to pick it simply because it has more traction, which is code for the following:
it will be along longer,
bugs should get fixed faster,
it should improve faster,
it should be more stable,
it might add a bit of veneer to your work because you're using the cool kids' tool.
However it seems that you're planning to specify a REST API. I'm not sure either tool is the right one for the job. Have you considered a combination of JSON Schema, JSON Hyper-Schema, and a documentation tool like prmd? This has the added benefits of being (highly) machine readable which can be used to generate test suites for implementations, clients for different programming languages, etc.
Full disclosure: I started off using ReSpec, added Markdown support to it, helped maintain it and recently switched to Bikeshed to benefit from its cross-spec linking database integration.
Given it's a REST-based API, W3C is most relevant. WHATWG is too focussed on HTML, IETF would result in a less readable spec, and potentially OASIS is too obscure.
All bodies agree on RFC2119, so it's worth ensuring this is used in the spec.
If the W3C is chosen, Pubrules must be followed (there is a new W3C pubrules validator, accessible via npm and here). Two main formats/tools are currently popular, both supported by the W3C's tooling, as described here:
ReSpec and Bikeshed: Since W3C "pubrules" markup can prove repetitive and at times hard to get right, many tools have been developed to assist people in producing it — these are the two main ones. ReSpec documents are essentially valid HTML with some extra configuration that a JS library turns into the real thing; Bikeshed is a Python preprocessor that can apply to HTML but is more often used in Markdown mode.
N.B. Anolis, an older preprocessor that preceded ReSpec and Bikeshed, has been declared dead by it's author.
W3C is currently undergoing a process of modernisation. A new W3C project named Echidna (based in GitHub) supports both ReSpec and Bikeshed automated publishing, though the latter has only recently been implemented, and it currently only works inside the W3C.
Using either of the above tools will allow the standard to be indexed in specref.org (the database of bibliographical references that W3C specifications rely upon).
Notes on each of these options:
ReSpec
ReSpec is in use at the W3C and actively maintained.
ReSpec apparently does support Markdown, but the feature is undocumented.
Spec Generator seems in common use in W3C for ReSpec CI, and can be accessed outside the W3C (it used to be internal).
In terms of CI alternatives:
Echidna is a new official recommendation for ReSpec CI, however it currently only works inside the W3C.
Publican is a GitHub hook listener that generates specs written to be parsed by ReSpec or Bikeshed. Hard to tell the status of the project though, as it appears to be discontinued (Robin originally created ReSpec, and did lots of work for webplatform.org, but the project may have since changed direction). Likely better to use actual Bikeshed for Bikeshed CI. It also runs in Docker (see gist).
There are various articles discussing the use of ReSpec with GitHub, and the publishing process.
Some say ReSpec is more accessible.
Examples of ReSpec specs: here, here, here, here
Examples of ReSpec CI: here (Echidna here, here)
Bikeshed
Bikeshed is in use at both the W3C and WHATWG, and is actively maintained.
Bikeshed fully supports Markdown (and soon CommonMark).
Bikeshed specs are compiled, so this works well for CI in terms of flagging syntax error (it's main advantage).
Need to set up Travis CI on the GitHub repo to publish changes, as the W3C have done.
Can use a watcher when editing locally to reduce dev cycle.
Can use a remotely hosted processor, but it won't work with all features (e.g. the separate biblio file).
There are a few examples of people migrating from ReSpec to Bikeshed, not the other way around.
HTML diff (not natively supported in Bikeshed, but found in ReSpec) can still be done by manually adapting ReSpec Section 5, as it's just a simple curl.
Given the use of Bikeshed for the current HTML5 spec, it would appear to be gaining popularity.
Examples of Bikeshed specs: here
Examples of Bikeshed CI: here, here, here, here
Both ReSpec and Bikeshed have a feature to link GitHub issues to inline issues in the spec, which mean they pair well with GitHub. All examples found just use commit logs for versioning.
In terms of community:
W3C community groups appear to be a good way to attract a broader audience, and they recommend using GitHub for "modern standards development" (and ReSpec, though that recommendation may be outdated).
The Web Incubator CG is an even more informal version of W3C Community Groups, which provides an existing community, GitHub, and forum to discuss topics directly related to the "web platform" (which means only useful for a "web platform feature that would be implemented in a browser or similar user agent"). They use both ReSpec and Bikeshed.
We currently keep our coding standard in a MSWord document under SVN.
As our standards grow / change, it's becoming an increasingly clunky beast to maintain.
Most entries currently consist of:
A succinct explanation of the guideline.
Reasoning behind the guideline.
Any extra notes.
Examples of what you should do.
Examples of what you should not to.
At the moment we use track changes within the document to keep track of pending suggestions / corrects which are periodically reviewed and then accepted / rejected.
Is there a de-facto good way of tackling maintaining a document like this?
A repository at GitHub would serve well. See example: https://github.com/airbnb/javascript - you can have discussions, track changes, accept/reject pull requests, etc.
Also it would help if you use auto-formatting tools plugged into your build process like https://golang.org/cmd/gofmt/ or https://github.com/thoughtbot/hound
I suggest you use plain text file (or HTML / some other markup file if you need some fancy formatting) under some version control system. We used Word's features for versioning and I like what Git offers much much more.
GITHUB: As an organization, if you maintain a private Github repository (not opensource, but leverage Github's strengths to maintain repository, allow distributed coding accessible to individuals within organization), you could upload your Coding Standards document to a Github repository, maintain a markdown document, which could have reviews/pull requests etc, as mentioned by Alex above
REVIEWBOARD: If your organization does not have a private Github repository, then I suggest you could choose this option, if your organization is performing code reviews through review board. ReviewBoard allows to review code by peers, maintain data of the different reviews, whether addressed, whether the version is allowed to be shipped etc. So, you could avail this feature of review board to review Coding Standards document. ReviewBoard has a feature of reviewing PDF documents. So, I guess by this option, you are maintaining a repository for CodingStandards document as well as providing an option of reviewing PDF document, which is tracked by ReviewBoard application.
Hope it helped. I guess there might be many other ways in which many companies might be doing.
Is there any CMS such as expression engine or wordpress that allows a user to click a button and convert all the text to another language (it would have to be human generated otherwise it has too many mistakes probably).
I'd like to know if there are any good solutions out there that work for real world use, in like business company websites.
Tridion CMS is designed to assist in website translation. They even have translation services to help you through the process of translating your content. It is not a cheap solution but is a viable solution.
As noted above - this is a huge topic and not easily answered briefly. But here are some things to consider...
NO CMS on the market today elegantly interoperates, out of the box, with translation technology for use in real-world translation projects. Reports from clients we've worked with have even raised concerns about the SDL integration.
At best - a handful of CMS's either offer very light-weight features that "appear" to help (side-by-side editing that prevents use of TM) but don't scale or have modest oem connectors to captive translation providers (CQ5<>TDC).
If your needs are modest - these might work fine.
But if you're serious about localization and have a moderate to high volume of content and want to work with any translation provider - you need a proper, rich, scalable integration between your CMS and the TMS (translation management system) used by your Translation firm (LSP).
Regrettably - these are scarce. We do nothing BUT build these connectors and use a neutral platform to provide direct integration all sorts of translation providers and technologies, the full SDL suite included - and still we've only been able to build a few rich CMS plug-in connectors because they are very complicated and require substantial development effort - IF they are going to be useful.
But the CMS choice you make should be driven as much by your broader needs. Localization should only be one facet of the decision process.
I guess the harsh reality is that there is NO CMS that will do what you descibe without smoe modification or a connector.
RK
I would recoomend you to use Kentico CMS.
See the video on Multilingual support in Kentico CMS:
http://devnet.kentico.com/Blogs/Martin-Hejtmanek/March-2010/Webinar-5---Multilingual-support-in-Kentico-CMS.aspx
Kentico CMS offers multilingual functionality including Right-to-Left languages and Eastern languages. Please see some "live" examples:
Site in 10 languages (incl. Chinese) : http://www.chep.com
Site in 7 languages (incl. Japan, Korean): http://www.wayoutback.com
Arabic: http://www.scb.gov.sa/
Hebrew: http://www.medicsfile.co.il/
Chinese: http://www.royalcaribbean-asia.com/?lang=zh-CN
Hindi site: http://www.rajasthantourism.gov.in/
More details on multiple languages support:
http://www.kentico.com/cms-asp-net-features/Content-management/Multiple-languages.aspx
Kentico also offers Translation Management:
http://devnet.kentico.com/docs/devguide/index.html?translation_management_overview.htm
Especially the translation status overview makes it really easy to manage multilingual web sites. If only a part of web site is translated then you can set to combine the rest with the original language without adding the missing pages in it manually.
By default Hippo CMS utilizes Google Translate, but you can plugin your own translation engine / review process. See for more information: http://www.cmswire.com/cms/web-cms/hippo-cms-75-launched-introduces-drag-drop-layout-localization-channel-management-010391.php/
If your organization already uses SDL for translation services then using SDL Tridion is a natural choice because of the built-in connector to send Tridion content for translation using a right-click on the GUI item. After translation, it is updated in the CMS and the author is notified.
SDL Bought Tridion a few years ago and has been maturing this solution since then. Today it is available in the current release, Tridion 2011 SP1, and is compatible with both World Server and Translation Management Server.
This is all human translation and any solution that honestly recommends machine translation for final content is not serious about it.
Drupal 8 is the best option available for Multilingual capability... Although you have to wait a little bit for its release, You will get a good result. Also earlier versions of drupal including Drupal 7 supports multilingual functionality.
But Drupal 8 will have more features...With Drupal 8 multilingual functionality, it is possible to translate anything in the system.
The multilingual functionality provides language configuration, assignment and detection functionality. It also provides a user interface to the existing back-end support for automatic software translation. Now it’s more easier to translate contents with the build-in user interfaces.
Plz refer the link for more detailed info Drupal 8- What’s new and Expected Inside
Day Communique (CQ5 - now ADEP), in combination with a third-party translation vendor, can do this job.
In Communique/ADEP, you manage your pages in whatever native language you choose. Once they are done, you kick off a translations workflow. This will go to your translation vendor (of which there are several). The vendor will have a human translate it, and possibly also use software to speed up the translation process. It will come back to you for approval in the workflow, if you wish. Otherwise, it will just be published to your web site.
So yes, from the user's perspective, one click can indeed translate a page in multiple languages, and publish it to multiple web sites. Our company is doing this, only we are doing our own in-house translation.
I have not used this, but I looked into it awhile ago and this looks to be the best solutions I have seen.
http://umbraco.org/blog/2009/3/25/microsoft-translator-and-umbraco
That is not how major businesses do translation. It's good for quick and dirty, general idea translation, but it's not for anyone serious about messaging to multiple languages and cultures. Typically, businesses work with translation vendors and grow translation memories that help to guide content authors to creating a consistent message and to reuse content (keeping translation costs down).
This is a big subject, not a small one. Honestly, I'm kind of flabbergasted at how to answer this question, so I'll stop here.
I've written some simple software which helps me manage and disseminate engineering data on a company intranet. It's pretty flexible about adapting to new content and I wonder if it justifies the description 'Content Management System.
A previous question: how to define content management did a pretty good job of defining a CMS, but I've a feeling my approach fails to reach the bar.
What is the minimum set of features considered essential in a Content Management System, and are there names for subsets of these features?
For example, I've seen some software described as a 'dashboard'. Is this a subset of a CMS?
I'm not really interested in testimonials for other CMS solutions.
It's a bit like Jazz, if you have to ask it's ain't ...
To my mind discussions about such terminology tend to be in the Marketing space. If your software is doing something useful, who cares what it is, or more to the point what label you put on the tin?
Came across a simple definition from a text from what you could possible consider an 'other CMS solution', but we web-frameworkers tend to have bizarre views on CMSs.
Content management systems (CMS)
let users create and edit pages on a
site dynamically through a web-based
interface. Sometimes called
brochureware site because they tend to be used in the same fashion as
traditional printed brochers handed
out by businesses.
Practical Django Projects, 1st ed. James Bennetts
http://www.apress.com/book/preview/9781590599969
Not the final answer, but one definition.
There are two ways to look at it. What is the name: "Content Management System". You could argue that if it is a system to manage content, it's a content management system (small letters). The other way to look at is user expectation. What does a test group of representative users or developers in your target audience expect when they hear CMS? Editing the textual content of a website comes to mind in this case.
If you want to provide a description useful to a broader audience, you have to understand their expectations. If your own interpretation is that those expectations would be unfulfilled, you might come up with a more specific label. Perhaps Engineering Data Management System, or something more specific to your purpose. I think you will be much happier with this.
Lastly, if you need to categorize it on some form of public resource website, you might have to go up or laterally from an existing CMS category. Or, use the category, but a more specific label for the product itself.